# Filters and segments

A filter narrows every number on the dashboard to the visits that match it: KPIs, the chart, every breakdown and revenue. Revenue follows the visit that gets the credit for each payment.

## Add a filter

- Click any row in a breakdown (a channel, a page, a country) to filter on it.
- Or click **Filter**, pick a dimension and an operator, and pick one or more values.

Several values of one filter mean "any of them": **Country is Portugal or Spain**. Different filters must all match: **Country is Portugal** and **Channel is not Direct**.

| Operator | Matches | URL parameter |
|---|---|---|
| is | the value exactly (any of the values) | `f_<key>=a,b` |
| is not | none of the values; empty values match | `fx_<key>=a,b` |
| contains | text inside the value, any case | `fc_<key>=a,b` |
| does not contain | values without the text; empty values match | `fxc_<key>=a,b` |

Keys: channel, referrer, campaign, keyword, source, hostname, entry, exit, country, region, city, browser, os, device, page, goal, visitor.

- `page` and `goal` match visits with at least one page view of that path, or one completion of that goal.
- `visitor` is `new` (the visitor's first visit) or `returning` (any later visit). It takes is and is not.
- `country` takes ISO codes (`PT`) or English names (`Portugal`). "contains" matches names: `fc_country=united` is the United States, the United Kingdom and the United Arab Emirates.
- `(none)` matches an empty value. For the referrer, `Direct` means no referrer.
- Separate values with commas. Write a comma inside a value as `\,`. The old form `f_country=PT` works as before.

Filters live in the URL, so a filtered view is a link you can share:

```
https://twelvebit.app/s/SITE_ID?f_channel=Organic%20Search,AI%20Assistants&fx_country=US&fc_page=/blog
```

## New and returning visitors

Hover or focus the **Visitors** tile to see how many people came for the first time in the range and how many came back. A visitor whose first visit falls in the range counts as new, even if they came back later in the same range. The filter `f_visitor=returning` keeps every return visit, so it can count a few more people than the "returning" figure on the tile.

## Chart any KPI

Click a KPI tile (Visitors, Revenue or your #1 goal, Conversion rate, Revenue/visitor, Bounce rate, Session time) to draw it on the main chart. The choice is in the URL as `?metric=`: `visitors`, `revenue`, `goal`, `conversion_rate`, `revenue_per_visitor`, `bounce_rate` or `session_time`. Visitors show as bars under the line, so a high rate on a quiet day reads as a quiet day.

## Segments

A segment is a saved set of filters with a name, for example "Paid traffic outside the US". Segments belong to the site, so the whole team sees them.

- **Apply**: open **Segments** in the toolbar and pick one. It replaces the filters on screen.
- **Save**: add filters, open **Segments**, type a name and click **Save**. A segment with the same name is replaced.
- **Delete**: click × next to the segment, then **Delete**.

Owners and members can save and delete segments. Viewers can apply them. A site keeps at most 50 segments. Public dashboards do not show segments.

## API and MCP

The REST API takes the same URL parameters on every analytics endpoint:

```bash
curl -sS "https://twelvebit.app/api/v1/overview?period=30d&f_country=PT,ES&fx_channel=Direct" -H "Authorization: Bearer $TWELVEBIT_API_KEY"
```

`GET /api/v1/segments` lists the segments, `POST /api/v1/segments` saves one (`{ "name": "…", "filters": { … } }`) and `DELETE /api/v1/segments?id=…` deletes one. Each segment has a `query` field: the filters as URL parameters, ready to append to any endpoint.

MCP tools take `filters` as an object. A string is "is", a list is "is any of", and an object picks the operator:

```json
{ "channel": ["Paid Search", "Paid Social"], "country": { "is_not": "US" }, "page": { "contains": "/pricing" }, "visitor": "returning" }
```

`list_segments` returns the saved segments with their filters, and `save_segment` saves one.

---

Source: https://twelvebit.app/docs/filters · All docs: https://twelvebit.app/llms.txt