# Reports

Everything an [analytics property](/docs/analytics) collects can be read in three places: the dashboard, the `splithub` CLI and the MCP server. They answer from the same reports, so an agent and a teammate looking at the dashboard see the same numbers. Reports are counts, not experiment results: for a verdict use `npx splithub results`.

Reports with dimensions, filters, visits and conversions are SplitHub Cloud features. A self-hosted property answers raw counts (see [Self-hosted](/docs/analytics#self-hosted)).

## Where to read them

| Report | Dashboard (property page) | CLI | MCP tool |
|---|---|---|---|
| Every property, last 30 days | Analytics | `npx splithub analytics` | `splithub_analytics` |
| Totals, goals, top pages and sources | Overview | `analytics <id>` | `splithub_analytics` with `property` |
| By a dimension | Pages, Sources, Audience, Events & goals | `analytics <id> --by <dimension>` | `splithub_analytics` with `by` |
| Funnels | Funnels | `analytics funnel <id>` | `splithub_analytics_funnel` |
| Paths | Paths | `analytics paths <id>` | `splithub_analytics_paths` |
| Retention | Retention | `analytics retention <id>` | `splithub_analytics_retention` |
| Right now | Realtime | `analytics realtime <id>` | `splithub_analytics_realtime` |
| Latest raw rows | Raw events | `analytics events <id>` | `splithub_analytics_events` |
| Event props | Events & goals | `analytics props <id> --event <name>` | — |
| CSV | Export | `analytics export <id>` | — |
| Notes | Notes | `npx splithub notes` | `splithub_notes` |
| Saved segments | the filter bar | `analytics segments` | `splithub_segments` |

Every CLI command takes `--json`. `npx splithub status` also lists each property's last 7 days against the 7 before, and `npx splithub report` adds them as an Analytics table.

## Totals

```bash
npx splithub analytics sh-x1h78w --days 7
npx splithub analytics sh-x1h78w --from 2026-10-01 --to 2026-10-31
```

Visitors, new visitors, identified users, visits, pageviews, events, bounce rate and visit duration, then each goal (conversions, completions, revenue), the top pages, the top sources and the notes in the range. The default range is the last 30 days; one report covers at most 400 days. Days follow the project's time zone (Settings).

## Dimensions

`--by` groups the report by one dimension:

| Group | Dimensions |
|---|---|
| Pages | `page`, `entry`, `exit` |
| Sources | `source`, `referrer`, `channel`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` |
| Audience | `country`, `region`, `city`, `device`, `os`, `browser`, `language`, `host` |
| Actions | `event`, `goal` |
| Your data | `trait --key plan` (an identify trait), `variant --experiment hero` (the variant each visitor saw) |

```bash
npx splithub analytics sh-x1h78w --by channel
npx splithub analytics sh-x1h78w --by source --goal signup     # conversions of signup per source
npx splithub analytics sh-x1h78w --by variant --experiment hero
npx splithub analytics sh-x1h78w --by trait --key plan
```

With a visit dimension, `--goal <key>` adds that goal's conversions per row.

## Filters

`--filter dimension=value[,value]` narrows the visits a report starts from. Repeat it to combine filters; several values of one filter mean any of them.

```bash
npx splithub analytics sh-x1h78w --by page --filter country=DE,FR --filter source="(none)"
```

Any visit dimension, `page` and `event` filter this way. Four prefixes reach your own data:

| Filter | Keeps visits |
|---|---|
| `p.gclid=abc` | whose landing page had that query parameter |
| `t.plan=pro` | of users with that identify trait |
| `e.signup.plan=pro` | that sent the event `signup` with that prop value |
| `x.hero=bold` | of visitors who saw that variant of the experiment |

## Compare

```bash
npx splithub analytics sh-x1h78w --days 7 --compare                      # the 7 days right before
npx splithub analytics sh-x1h78w --days 7 --compare year                 # the same days a year earlier
npx splithub analytics sh-x1h78w --compare 2026-08-01..2026-08-31        # days you choose
```

The answer gains `previous`, and the CLI prints the change per row.

## Segments

A segment is a saved set of filters that every report can apply.

```bash
npx splithub analytics segments --save "German traffic" country=DE
npx splithub analytics sh-x1h78w --segment "German traffic" --by page
npx splithub analytics segments                                   # the list
npx splithub analytics segments --delete "German traffic"
```

`--property <id>` keeps a segment to one property. A `--filter` on the same dimension wins over the segment's.

## Funnels

```bash
npx splithub analytics funnel sh-x1h78w --steps "page:/,event:Signup,goal:paid"
npx splithub analytics funnel sh-x1h78w --steps "page:/pricing,goal:paid" --within 7d --by country
```

Two to eight steps: `page:/path` (patterns like `page:/blog/*` work), `event:<name>` or `goal:<key>`. Visitors count for a step only after the steps before it. `--within` is `visit` (the default, all in one visit), `7d` or `30d` from the first step. Each step answers `visitors`, `conversion` (share of step 1) and `dropoff` (share lost since the step before).

## Paths

```bash
npx splithub analytics paths sh-x1h78w --page /pricing           # where visits went next
npx splithub analytics paths sh-x1h78w --page /pricing --prev    # where they came from
```

Rows are pages with their visits; `(exit)` means the visit ended there, `(entrance)` that it started on the page.

## Retention

```bash
npx splithub analytics retention sh-x1h78w
npx splithub analytics retention sh-x1h78w --start event:Signup --return visit --period day
```

Visitors are grouped by the day or week they started (`--start visit`, `event:<name>` or `goal:<key>`), and each cohort shows how many came back (`--return visit` or `event:<name>`) in each period after. The default is visit to visit, by week.

## Realtime

```bash
npx splithub analytics realtime sh-x1h78w
```

Visitors in the last 5 minutes, pageviews and events per minute over the last 30 minutes, top pages and sources. The quickest check that tracking works after a deploy.

## Event props

```bash
npx splithub analytics props sh-x1h78w --event Signup             # the prop names of Signup
npx splithub analytics props sh-x1h78w --event Signup --key plan  # the values of one prop
```

## Export

```bash
npx splithub analytics export sh-x1h78w --by day > daily.csv
npx splithub analytics export sh-x1h78w --by page > pages.csv
npx splithub analytics export sh-x1h78w --raw > events.csv
```

CSV to stdout, for the range and filters you pass. `--raw` exports the raw tail (see [Retention](/docs/cloud#retention)).

## Notes

A note marks a day on every chart, so a jump in traffic has its reason next to it.

```bash
npx splithub notes add "Launched new pricing" --kind win --property sh-x1h78w --day 2026-10-05
npx splithub notes --property sh-x1h78w
```

Add one whenever you ship something that may move traffic.

## Alerts

Alerts on a property are a Pro feature, set in the dashboard (Alerts) or with the CLI:

```bash
npx splithub alerts add traffic_drop --property sh-x1h78w --percent 50
npx splithub alerts add traffic_spike --property sh-x1h78w --percent 50
npx splithub alerts add goal_silent --property sh-x1h78w --goal signup --hours 24
npx splithub alerts add event_count --property sh-x1h78w --event Signup --count 1000 --repeat
```

The digest covers properties too: visitors, top sources and pages, goals and events against the period before. Channels and schedules: [Alerts, digest, AI reviews](/docs/alerts).

## Words

| Word | Meaning |
|---|---|
| visitor | one browser, by its `sh_vid` cookie |
| user | a visitor you identified with `identify()` |
| visit | a run of pageviews and events that ends after 30 minutes without any (`sessions` in JSON) |
| bounce | a visit with one page and no event; bounce rate is bounces divided by visits |
| duration | time in a visit, in milliseconds in JSON |
| source | the UTM source, or the referrer's site (Google, Facebook…); `(none)` is direct |
| channel | sources grouped: Direct, Organic Search, Paid Search, Organic Social, Paid Social, Email, Referral, Affiliate, Other |
| entry, exit | the first and the last page of a visit |
| conversion | a visitor reaching a goal, counted once per visitor in the range |
| completions | how many times the goal happened |

Bots are never counted.

## For agents

The [analytics skill](/docs/agent-skills) that `npx splithub skills` installs teaches an agent these commands. Ask it in plain words ("where did signups come from last week?", "how many visitors reach checkout from pricing?") and it picks the report, the range and the filters, and quotes the counts as they are.