Merge pull request #586 from plausible/metmarkosaric-patch-28

Document Segments feature: How to create and how to use in API

Author: apata

docs/filters-segments.md

@@ -1,18 +1,20 @@
 ---
-title: Using filters to segment your audience
+title: Filter and segment your audience
 ---
 
 import useBaseUrl from '@docusaurus/useBaseUrl';
 
-Plausible Analytics allows you to easily segment your audience to analyze and understand the different trends. A segment is made up of one or more filters. 
+Plausible Analytics allows you to easily segment your audience to analyze and understand the different trends. A segment is made up of one or more filters. You can save any segment for quick and convenient access.
+
+## How to filter your dashboard 
 
 Any metric you click on in your dashboard creates a new filter. Click on any referral source, any of your pages or any location, device or goal and your dashboard will then show only the traffic for the metric you have selected.
 
 You can mix and match filters too. So you can click on a referral source, then click on a country and then a goal to see all the traffic sent by the chosen referral source that is based in the selected country and that has converted on the selected goal.
 
 Your current filters will be displayed on the top of your dashboard. You can click on the name of the existing filter to edit it or on the `x` icon to remove it. 
 
-You can remove all your filters by hitting the `Esc` key on your keyboard or by selecting `Clear all filters` in the filters menu that shows up when you're using multiple filters.
+You can remove all your filters by hitting the `Esc` key on your keyboard or by selecting `Clear all filters` in the filters menu (`***`).
 
 <img alt="Mix and match filters to segment your audience" src={useBaseUrl('img/filter-by-source-and-country.png')} />
 
@@ -64,4 +66,24 @@ Learn more on how Plausible [handles cross-subdomain tracking here](subdomain-ho
 
 <img alt="List of subdomains" src={useBaseUrl('img/list-of-hostnames-and-subdomains.png')} />
 
+## How to save a segment 
+
+Click on any metric in the dashboard or use the "**Filter**" button to filter your audience to a desired segment. After completing your segment, click on the "**Save as segment**" button that is visible in the filters menu (`***`) that you see when your dashboard is filtered.
+
+Segments can be saved either as "**personal segments**" (these are visible only to you) or as "**site segments**" (these are visible to all the team members that have access to your dashboard).
+
+Choose the type of segment you want to create, give it a recognizable name and click on the "**Save**" button.
+
+### How to open a previously saved segment
+
+Click the "**Filter**" button in the top-right corner of your dashboard to view your saved segments under the "**Segments**" heading. You can also search for specific segments. Click on a segment to open it in your dashboard. 
+
+Note that the "**Segments**" heading will only be visible in the "**Filter**" button after you save your first segment. 
+
+### How to edit or delete a previously saved segment
+
+Open a previously saved segment and click its name in the top line of your Plausible dashboard. Then, select "**Edit segment**" to add or remove filters. 
+
+To save your changes, click the "**Update segment**" button. Use the arrow next to this button to save the existing segment as a brand new segment ("**Save as a new segment**) or to delete the existing segment ("**Delete segment**").
+
 P.S. We've written an in-depth guide on effective use of audience segmentation, you can [read it here](https://plausible.io/audience-segmentation).

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 {