Behavioral filtering docs

docs/stats-api.md

@@ -136,6 +136,7 @@ Valid dimensions include:
 | --- | --- | --- |
 | `event:goal` | Register | A custom action that you want your users to take. To use this property, you first need to configure some goals in the [site settings](/website-settings), or via the [Sites API](/sites-api). The value is the goal's `display_name`. Learn more about goals [here](/goal-conversions). |
 | `event:page` | /blog/remove-google-analytics | Pathname of the page where the event is triggered. You can also use an asterisk to group multiple pages (`/blog*`) |
+| `event:name` | Custom Event | Name of the event or [custom event](/docs/custom-event-goals.md) to filter by. |
 | `event:hostname` | example.com | Hostname of the event. |
 
 :::warning
@@ -235,7 +236,7 @@ List of values to match against. A data point matches filter if _any_ of the cla
 
 `["contains", "event:country", ["united", "EST], { "case_sensitive": false }]`. [See full example](#example-filtering-case-insensitive)
 
-#### Logical operations
+#### Logical filters
 
 Filters can be combined using `and`, `or` and `not` operators.
 
@@ -247,6 +248,20 @@ Filters can be combined using `and`, `or` and `not` operators.
 
 Note that top level filters is wrapped in an implicit `and`.
 
+#### Behavioral filters
+
+Behavioral filters can be used to filter whether a user has ever done or not done something. This can be used to filter out users who have not completed a goal or
+who have visited a particular page.
+
+| Operator | Example | Explanation |
+| -- | -- | -- |
+| `has_done` | `["has_done", ["is", "event:page", ["/pricing"]]]` | Users who have done a pageview to /pricing page |
+| `has_not_done` | `["has_not_done", ["is", "event:goal", ["Login"]]]` | Users who have not done Login goal |
+
+Behavioral filters can only be used with [event dimension](#event-dimensions) filters.
+
+[See example](#example-behavioral-filters)
+
 ### order_by <Optional />
 
 Allows for custom ordering of query results.
@@ -388,6 +403,12 @@ The following examples are interactive and can be edited and run against your ow
 
 <ApiV2Example id="example-filtering-case-insensitive" />
 
+### Behavioral filters {#example-behavioral-filters}
+
+This example shows how many visitors and how many times visitors have visited the `/pricing` page, needed support before or after and not created an account or logged in.
+
+<ApiV2Example id="example-behavioral-filters" />
+
 ### Timeseries query {#example-timeseries}
 
 <ApiV2Example id="example-timeseries" />
@@ -414,7 +435,6 @@ In this example, imported data could not be included due to dimension and filter
 
 <ApiV2Example id="example-imports-warning" />
 
-
 ### Revenue metrics {#example-revenue-metrics}
 
 <ApiV2Example id="example-revenue-metrics" />

src/js/apiv2-examples/behavioral-filters-query.json

@@ -0,0 +1,10 @@
+{
+  "site_id": "dummy.site",
+  "metrics": ["visitors", "pageviews"],
+  "date_range": "7d",
+  "filters": [
+    ["is", "event:page", ["/pricing"]],
+    ["has_done", ["is", "event:goal", ["Open Support Chat"]]],
+    ["has_not_done", ["is", "event:goal", ["Register", "Login"]]]
+  ]
+}

src/js/apiv2-examples/behavioral-filters-response.json

@@ -0,0 +1,18 @@
+{
+  "results": [{"metrics": [1533, 3429], "dimensions": []}],
+  "meta": {},
+  "query": {
+    "site_id": "dummy.site",
+    "metrics": ["visitors", "pageviews"],
+    "date_range": ["2025-01-10T00:00:00+00:00", "2025-01-16T23:59:59+00:00"],
+    "filters": [
+      ["is", "event:page", ["/pricing"]],
+      ["has_done", ["is", "event:goal", ["Open Support Chat"]]],
+      ["has_not_done", ["is", "event:goal", ["Register", "Login"]]]
+    ],
+    "dimensions": [],
+    "order_by": [["visitors", "desc"]],
+    "include": {},
+    "pagination": {"offset": 0, "limit": 10000}
+  }
+}

src/js/examples.tsx

@@ -88,6 +88,12 @@ const EXAMPLES = [
     title: "Revenue metrics could not be calculated",
     query: read("apiv2-examples/revenue-warning-query.json"),
     exampleResponse: read("apiv2-examples/revenue-warning-response.json"),
+  },
+  {
+    id: "example-behavioral-filters",
+    title: "Behavioral filters",
+    query: read("apiv2-examples/behavioral-filters-query.json"),
+    exampleResponse: read("apiv2-examples/behavioral-filters-response.json"),
   }
 ]