What the numbers mean

This page defines every number and every dimension that misomoon reports, as the code computes them. The dashboard, the Stats API, and the MCP tools call the same functions in apps/api/src/stats.ts, which build their SQL in packages/core/src/queries.ts, so one number means the same thing everywhere. The API reference lists the parameters and response fields. Use the dashboard shows where each number appears.

#Headline metrics

The KPI tiles, GET /api/v1/stats/aggregate, and every point of GET /api/v1/stats/timeseries return these nine metrics. A metric read from events counts the events whose time falls in the period. A metric read from visits counts the visits that started in the period.

pageviews and views_per_visit can disagree. pageviews counts views by their own time, and views_per_visit counts the views of visits that started in the period, even when a view happened after the period ended.

Each site has one reporting currency, USD unless you set another. revenue and average_revenue count the events in that currency and the events sent without a currency. They never add up amounts in different currencies. The amount on a tracker or SDK event is kept between 0 and 1,000,000,000. Refunds come from payment webhooks as negative amounts. Connect payments explains how a payment finds its visit.

#Compare with an earlier period

With compare=previous the comparison period is the stretch of the same length right before the current one. With compare=year it is the same dates a year earlier. change holds one value per metric:

#A visitor id lasts one UTC day

misomoon sets no cookies and stores nothing on the device. To count people, the Worker hashes a random salt, the site id, the IP address, and the user agent with SHA-256, and keeps the first 16 hex characters as visitor_id (visitorId in packages/core/src/ingest.ts). Each UTC day has its own salt. The Worker makes it on first use and keeps it in the salts table of CONTROL. The hourly maintenance job deletes salts that are more than two days old. The IP address is never stored.

These rules follow from the daily salt:

• The same person gets a new id at 00:00 UTC. A visitor count over several days is the sum of each UTC day's unique visitors. Someone who visits on 5 days of a month counts 5 times in that month's visitors.
• The salt rotates at 00:00 UTC, not at the site's local midnight. A local day, a today period, or a 24h period that spans 00:00 UTC can count one person twice.
• Two people behind one IP address with the same user agent share an id that day. One person on two devices, or with two browsers, has two ids.
• Breakdown rows, funnels, paths, and page interaction reports count visitors by the same id.

Why is a visitor unique only for one day? gives the short answer.

#Unique counts add up across shards

A site's data lives in ranges of whole UTC days, one shard per range (Sharding). A day never spans two shards, and an id never lasts past its day, so no visitor appears on two shards. misomoon counts distinct visitors on each shard and adds the counts. For a rate such as bounce_rate, it adds the numerators and the denominators of every shard first and divides once. It never averages a rate across shards.

#A visit ends after 30 minutes without activity

A visit, called a session in the code, is a run of events from one visitor id. The Worker assigns each event to a visit in assignSessions in packages/core/src/ingest.ts, with SESSION_GAP set to 30 minutes:

A visit takes its source, channel, referrer, UTM tags, hostname, location, browser, operating system, device, screen, and language from its first event, and keeps them. Reports read these columns of the visit, which the Worker updates as events arrive:

Payments never change a visit. A Payment or Refund row joins the visit's visitor id only when the payment comes on the UTC day of the visit. Otherwise its visitor_id is empty and no visitor count includes it.

#A bounce is a visit with one pageview and no interaction

A visit is a bounce when it has at most one pageview and no interactive custom event. The SQL test is pageviews <= 1 AND events = 0 on the visit's row.

Under a page filter, bounce rate counts only the visits that entered on a matching page, in the numerator and in the denominator. A page row in a breakdown takes its bounce rate from the visits that entered on that page.

Imported history from Google has no bounces, so misomoon counts a session that Google didn't mark as engaged as a bounce.

#Visit duration and time on page measure different things

m.js sends an engagement ping when the page is hidden or the route changes. It doesn't send one for under one second of engaged time, unless a feature, such as clicks or Web Vitals, has data to send. The Worker keeps at most 6 hours of engaged time per ping. A visit that opens the same page twice adds the engaged time of both views. Time on page divides the summed time of each page by the number of visits that sent time for it.

#Scroll depth is the deepest point of each visit

The tracker records the lowest point of the page that came into view: the scroll position plus the window height, as a percent of the page height. The Worker keeps it between 0 and 100 and rounds it to a whole number. A page that fits in the window reports 100.

Scroll depth is always on. It needs no feature box.

#Breakdown rows

GET /api/v1/stats/breakdown?property=<name> returns one row per value. Each row has key, visitors, visits, pageviews, events, bounce_rate, and visit_duration. What those fields count depends on the kind of property:

bounce_rate and visit_duration on a row follow the rules for the headline metrics, over the row's visits. On a page row they describe the visits that entered on that page.

These rules hold for every breakdown:

• A row with no value has the key (none). The dashboard shows it as Direct / none for source and referrer, (not set) for the UTM dimensions, and Unknown for the rest.
• Rows sort by visitors, then by pageviews, then by key.
• Each shard returns its top 500 values. When one shard reached that cap, the response has truncated: true, and rare values may be missing.
• limit takes 1 to 200 rows, and has_more says whether another page exists.
• search keeps the values that contain the text. The search runs on each shard, so it finds values outside the top 500.

#Goals count visitors who reached them

A goal is an event name or a page path. Its row counts the visitors who sent the event or had a pageview or custom event on a matching page. For a page goal, events is the number of matching pageviews, and revenue is 0. Only event goals carry revenue. goal==<name> as a filter turns into the goal's event or page filter.

Goal rows read only the events misomoon collected. In a report without filters, the visitors that conversion_rate divides by include imported history, so the rate reads lower over a period with imported days. Conversion rate and Matching rules have the details.

#Web Vitals

GET /api/v1/stats/vitals and Speed report five Web Vitals from real visits. They need the Web Vitals (vitals) feature (Choose what to track).

A value is good at or under the good limit, poor over the poor limit, and needs_improvement in between. samples is the number of values.

The tracker sends one set of values per page load, with the page's first engagement ping. Route changes in a single-page app send none, and a vital the browser didn't measure is left out. The Worker keeps times between 0 and 60,000 ms and CLS between 0 and 10.

p75 is the 75th percentile, read from a histogram that every shard fills:

misomoon adds the bins of every shard, finds the bin where three quarters of the values are reached, and reports the middle of that bin. p75 is null without samples. The dashboard rates a tile by its p75 with the limits above.

#Channels

classify in packages/core/src/channel.ts gives each visit one of 11 channels. It reads the visit's first event: the referrer host, the UTM tags, and the page URL. The rules run in this order, and the first rule that matches wins:

utm_medium is compared in lower case. A visit has a paid signal when its page URL has a gclid or msclkid parameter, or utm_medium is cpc, ppc, paidsearch, paid_search, cpm, cpv, or cpa, or starts with paid.

#Sources and referrers

The referrer dimension is the host of document.referrer, with a leading www. and then a leading m. removed. A referrer from the page's own host, compared without www., is no referrer, so moving between pages of the site is never a referral. A link from another subdomain of your site is a referral.

The source dimension is the first of these that has a value:

1. The name of a known referrer host, from the table below.
2. utm_source, tidied. A value equal to the first part of a known host takes that source's name, so google becomes Google. Other values of 3 characters or fewer become upper case, and longer values get a capital first letter.
3. The referrer host.
4. Direct.

utm_source reads the utm_source parameter of the landing URL, then ref, then source. A known referrer wins over utm_source. An unknown referrer loses to it, and the referrer dimension still holds the host.

Hosts without a trailing dot match the host itself and its subdomains. Hosts with a trailing dot, such as google., match any host that starts with it or contains it after a dot, such as google.de and google.co.uk. Exact hosts are checked first, so gemini.google.com is Gemini and mail.google.com is Gmail.

misomoon also stores the referrer URL without its query string. No report breaks it down.

#Dimensions

Every breakdown and filter takes one of these 26 dimensions (DIMENSIONS in packages/core/src/filters.ts). GET /api/v1/meta/dimensions returns them with their labels. The label is what the dashboard's filter bar shows.

Each dimension has a scope. An event dimension is a value of each event. A visit dimension is stored on the visit and on each of its events. An entry or exit dimension exists only on the visit. A visit matches an event filter when any of its events match, and an event matches an entry or exit filter when its visit does.

These names work in some places only:

A filter value of (none) matches events or visits without a value. Filters has the operators and limits.

#Other reports

#Live

GET /api/v1/stats/realtime and Live ignore the period and apply the filters.

Each window runs one minute past the current time, so an event from a browser whose clock runs a little fast still shows.

#Funnels and paths

A funnel step counts the visitors who reached it, and conversion is that count as a percent of the first step's visitors, to 1 decimal. dropoff is the previous step's visitors minus this step's, and never below 0. entered counts the distinct visitors with a pageview or custom event in the period. A visitor id lasts one UTC day, so a visitor's steps must happen on one UTC day. Paths count pageviews in visit order, with reloads of the same page folded into one, and each row's share is a percent of the visitors who followed the path. Funnel modes and Paths have the rules.

#Page interactions

GET /api/v1/stats/behavior reads the counts that engagement pings carry. Every count on a ping is the change since the previous ping, so the sums are exact.

Each report's visitors counts distinct visitors per row, such as the visitors who hit an error. See what people do on a page says what the tracker collects for each report.

#Search terms come from Google

The search_term breakdown asks Google Search Console for the period when you request it, and caches the answer for ten minutes. Its numbers come from Google, so they cover only the days Google has processed, usually up to two or three days ago.

Google can filter only by page and device. source==Google and channel==Organic Search change nothing, because every row is Google search traffic. Any other filter returns 400.

#Periods follow the site's time zone

Each site has an IANA time zone. An unknown zone name falls back to UTC. misomoon looks up the zone's offset for each instant, so a day starts at local midnight on both sides of a daylight saving change (time.ts in packages/core/src/time.ts).

A period that ends now runs one minute past the current time. A custom period ends at that point too when to is today.

The default interval for all and custom depends on the period's length:

interval picks another interval. Minute buckets start on UTC minutes. Hour buckets start on local hours. Day buckets start at local midnight, week buckets on Monday at local midnight, and month buckets on the first of the month at local midnight. A series holds at most 1,500 buckets. A longer series returns 400 with the number of buckets and asks for a coarser interval. Buckets without data come back as zeros.

#Imported history joins unfiltered reports

History imported from Google or from CSV files lands in each shard's imported table as daily totals per dimension and value (packages/core/src/imported.ts). misomoon adds it to a report only when the report has no filters. imported=0 leaves it out. Bring your history shows how to import.

Imported visitors are each day's unique visitors, so adding days matches how misomoon counts its own visitors.

Google reports name metrics differently. misomoon reads them this way:

#What misomoon drops

These events never reach a report:

An event whose client timestamp is more than 5 minutes from the server's clock keeps the event and takes the server's time instead. Why are my numbers lower than in Google Analytics? lists other reasons why counts differ between tools.