Show how segment can be used in Stats API

docs/stats-api.md

@@ -237,6 +237,10 @@ 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)
 
+#### Segments
+
+[Segments](/filters-segments/#how-to-save-a-segment) can be used in filters, in the form `["is", "segment", [<segment_id>]]`. [See example](#example-filtering-by-segment)
+
 #### Logical operations
 
 Filters can be combined using `and`, `or` and `not` operators.
@@ -390,6 +394,10 @@ The following examples are interactive and can be edited and run against your ow
 
 <ApiV2Example id="example-filtering-case-insensitive" />
 
+### Filtering by segment {#example-filtering-by-segment}
+
+<ApiV2Example id="example-filtering-by-segment" />
+
 ### Timeseries query {#example-timeseries}
 
 <ApiV2Example id="example-timeseries" />

src/js/apiv2-examples/filtering-by-segment-query.json

@@ -0,0 +1,6 @@
+{
+  "site_id": "dummy.site",
+  "metrics": ["visitors", "events"],
+  "filters": [["is", "segment", [2]]],
+  "date_range": "7d"
+}

src/js/apiv2-examples/filtering-by-segment-response.json

@@ -0,0 +1,17 @@
+{
+  "results": [{"metrics": [0, 0], "dimensions": []}],
+  "meta": {},
+  "query": {
+    "site_id": "dummy.site",
+    "metrics": ["visitors", "events"],
+    "date_range": ["2025-02-27T00:00:00+00:00", "2025-03-05T23:59:59+00:00"],
+    "filters": [
+      ["has_not_done", ["is", "event:goal", ["Signup"]]],
+      ["is", "visit:source", ["opensource.com"]]
+    ],
+    "dimensions": [],
+    "order_by": [["visitors", "desc"]],
+    "include": {},
+    "pagination": {"offset": 0, "limit": 10000}
+  }
+}

src/js/examples.tsx

@@ -88,7 +88,14 @@ 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-filtering-by-segment",
+    title: "Filtering by segment",
+    query: read("apiv2-examples/filtering-by-segment-query.json"),
+    exampleResponse: read("apiv2-examples/filtering-by-segment-response.json"),
   }
+
 ]
 
 export function getExampleCode(field: "query" | "exampleResponse", id: string, selectedSite: string | null): string {