feat(flags): included evaluated_at properties in $feature_flag_called events (#374)

* format

* update tests

* bump version

Author: dmarticus

CHANGELOG.md

@@ -1,3 +1,8 @@
+# 7.2.0 - 2025-12-01
+
+feat: add $feature_flag_evaluated_at properties to $feature_flag_called events
+
+
 # 7.1.0 - 2025-11-26
 
 Add support for the async version of Gemini.

posthog/client.py

@@ -1419,6 +1419,7 @@ def _get_feature_flag_result(
         flag_result = None
         flag_details = None
         request_id = None
+        evaluated_at = None
 
         flag_value = self._locally_evaluate_flag(
             key, distinct_id, groups, person_properties, group_properties
@@ -1443,13 +1444,15 @@ def _get_feature_flag_result(
                 )
         elif not only_evaluate_locally:
             try:
-                flag_details, request_id = self._get_feature_flag_details_from_server(
-                    key,
-                    distinct_id,
-                    groups,
-                    person_properties,
-                    group_properties,
-                    disable_geoip,
+                flag_details, request_id, evaluated_at = (
+                    self._get_feature_flag_details_from_server(
+                        key,
+                        distinct_id,
+                        groups,
+                        person_properties,
+                        group_properties,
+                        disable_geoip,
+                    )
                 )
                 flag_result = FeatureFlagResult.from_flag_details(
                     flag_details, override_match_value
@@ -1488,6 +1491,7 @@ def _get_feature_flag_result(
                 groups,
                 disable_geoip,
                 request_id,
+                evaluated_at,
                 flag_details,
             )
 
@@ -1691,9 +1695,9 @@ def _get_feature_flag_details_from_server(
         person_properties: dict[str, str],
         group_properties: dict[str, str],
         disable_geoip: Optional[bool],
-    ) -> tuple[Optional[FeatureFlag], Optional[str]]:
+    ) -> tuple[Optional[FeatureFlag], Optional[str], Optional[int]]:
         """
-        Calls /flags and returns the flag details and request id
+        Calls /flags and returns the flag details, request id, and evaluated at timestamp
         """
         resp_data = self.get_flags_decision(
             distinct_id,
@@ -1704,9 +1708,10 @@ def _get_feature_flag_details_from_server(
             flag_keys_to_evaluate=[key],
         )
         request_id = resp_data.get("requestId")
+        evaluated_at = resp_data.get("evaluatedAt")
         flags = resp_data.get("flags")
         flag_details = flags.get(key) if flags else None
-        return flag_details, request_id
+        return flag_details, request_id, evaluated_at
 
     def _capture_feature_flag_called(
         self,
@@ -1718,6 +1723,7 @@ def _capture_feature_flag_called(
         groups: Dict[str, str],
         disable_geoip: Optional[bool],
         request_id: Optional[str],
+        evaluated_at: Optional[int],
         flag_details: Optional[FeatureFlag],
     ):
         feature_flag_reported_key = (
@@ -1741,6 +1747,8 @@ def _capture_feature_flag_called(
 
             if request_id:
                 properties["$feature_flag_request_id"] = request_id
+            if evaluated_at:
+                properties["$feature_flag_evaluated_at"] = evaluated_at
             if isinstance(flag_details, FeatureFlag):
                 if flag_details.reason and flag_details.reason.description:
                     properties["$feature_flag_reason"] = flag_details.reason.description

posthog/test/test_feature_flags.py

@@ -3859,6 +3859,7 @@ def test_capture_is_called_with_flag_details(self, patch_flags, patch_capture):
                 },
             },
             "requestId": "18043bf7-9cf6-44cd-b959-9662ee20d371",
+            "evaluatedAt": 1234567890,
         }
         client = Client(FAKE_TEST_API_KEY)
 
@@ -3878,6 +3879,7 @@ def test_capture_is_called_with_flag_details(self, patch_flags, patch_capture):
                 "$feature_flag_id": 23,
                 "$feature_flag_version": 42,
                 "$feature_flag_request_id": "18043bf7-9cf6-44cd-b959-9662ee20d371",
+                "$feature_flag_evaluated_at": 1234567890,
             },
             groups={},
             disable_geoip=None,

posthog/types.py

@@ -123,6 +123,7 @@ class FlagsResponse(TypedDict, total=False):
     errorsWhileComputingFlags: bool
     requestId: str
     quotaLimit: Optional[List[str]]
+    evaluatedAt: Optional[int]
 
 
 class FlagsAndPayloads(TypedDict, total=True):

posthog/version.py

@@ -1,4 +1,4 @@
-VERSION = "7.1.0"
+VERSION = "7.2.0"
 
 if __name__ == "__main__":
     print(VERSION, end="")  # noqa: T201