@spec active_visitors(pos_integer(), String.t() | nil) :: non_neg_integer()

Distinct visitors seen in the last minutes — the "right now" number.

@spec browsers(filter(), keyword()) :: [map()]

Browser breakdown.

@spec bucket_for(String.t()) :: :hour | :day | :month

The bucket size a period should be charted at.

Short windows get hourly points; a year gets monthly ones, so the chart never tries to draw 365 bars.

@spec channels(filter(), keyword()) :: [map()]

Traffic grouped by channel — direct, organic, social, referral, email, paid.

@spec countries(filter(), keyword()) :: [map()]

Country breakdown.

Empty unless a geo resolver is configured or the host sits behind a CDN that sets a country header — see PhoenixKitWebAnalytics.Geo.

@spec daily_timeseries(filter()) :: [map()]

Daily page views and visitors, rolled-up days included — each entry %{date: Date.t(), pageviews: n, visitors: n, source: :events | :rollup}, where source says which a day was read from.

@spec default_period() :: String.t()

The default period when none was requested.

@spec devices(filter(), keyword()) :: [map()]

Device class breakdown (desktop / mobile / tablet).

@spec engagement(filter()) :: %{
  exits: non_neg_integer(),
  avg_time_ms: float() | nil,
  avg_scroll: float() | nil
}

How long visitors stay: exits (pages left), avg_time_ms (average time on a page, from leave events), and avg_scroll (average scroll depth, 0–100, nil without the client script).

@spec exit_pages(filter(), keyword()) :: [map()]

The pages visitors left the site from, ranked (pageviews holds the exit count).

@spec filter(keyword()) :: filter()

Builds a filter.

Options

• :period — one of periods/0's values; an unknown value falls back to the default rather than raising, since it arrives from a query parameter
• :site, :path — optional restrictions
• :bots — include automated traffic (default false)
• :now — reference time (tests)

@spec languages(filter(), keyword()) :: [map()]

Browser language breakdown.

@spec operating_systems(filter(), keyword()) :: [map()]

Operating system breakdown.

@spec overview(filter()) :: map()

Headline totals for the window.

Returns pageviews, visitors, sessions, events, bounce_rate (percent, nil with no sessions), avg_session_seconds (nil with no sessions), and avg_response_ms (nil when nothing recorded a duration).

@spec page_engagement(filter(), [String.t()]) :: %{required(String.t()) => map()}

Per-path engagement for the given paths: %{path => %{exits, avg_time_ms, avg_scroll}}. Paths with no leave recorded are absent.

@spec period_label(String.t()) :: String.t()

The human label for a period value.

@spec period_range(String.t(), DateTime.t() | nil) :: {DateTime.t(), DateTime.t()}

The {from, to} window for a period label, to exclusive.

iex> {from, to} = PhoenixKitWebAnalytics.Reports.period_range("today", ~U[2026-03-04 10:00:00Z])
iex> {DateTime.to_date(from), DateTime.to_date(to)}
{~D[2026-03-04], ~D[2026-03-05]}

@spec periods() :: [{String.t(), String.t()}]

The selectable periods as {value, label} pairs, for the UI.

@spec previous_overview(filter()) :: map() | nil

Totals for the window immediately before this one, for period-over-period comparison. nil for the "all" period, which has no "before".

@spec recent_hits(filter(), keyword()) :: [PhoenixKitWebAnalytics.Schemas.Event.t()]

The most recent hits, newest first — the live feed.

Returns whole PhoenixKitWebAnalytics.Schemas.Event structs. Every column is already non-identifying, so there is nothing to redact for display.

Options

• :limit — default 50
• :event_type — "pageview", "event", "interaction" or "leave" to show one kind only

@spec recent_sessions(pos_integer(), keyword()) :: {[map()], DateTime.t() | nil}

Visits with any activity in the last minutes, most recently active first — {rows, next_before} like sessions_page/2.

Reads the newest events through the time index and keeps the first limit distinct visits, so it costs the same with ten people online or ten thousand.

Options

• :limit — default 50
• :before — a DateTime; only visits whose latest hit is older (paging)

@spec session_summary(String.t()) :: map() | nil

One visit's totals over all its events, however long the visit — %{started, seconds, pageviews, actions, max_scroll, bot?, bot_reason}, or nil. bot_reason says why a visit counts as a bot's when its behaviour gave it away (see PhoenixKitWebAnalytics.BotSignals).

@spec session_timeline(String.t(), keyword()) :: [
  PhoenixKitWebAnalytics.Schemas.Event.t()
]

The events of one session, oldest first — the visit replayed. :limit caps how many (default 1000; the visit page asks for 500 at a time); [] for an id that isn't a UUID.

@spec sessions(filter(), keyword()) :: [map()]

Visits in the window, newest first — one row per visit that has at least one page view:

%{session_id, started_at, ended_at, seconds, pageviews, interactions,
  entry_path, exit_path, source, medium, browser, os, device_type,
  country_code, user_uuid}

source/medium are the first page view's. seconds spans every event type, so a visit that ended with a leave counts the time on its last page.

Built to stay cheap on a busy site: it pages through visit starts (the indexed session_start rows) and only then sums up the visits on the page, instead of grouping every event in the window. With a path filter it lists visits that landed on that page.

Options

• :limit — default 50
• :before — a DateTime; only visits that started before it (paging)
• :user_uuid — only visits in which that signed-in user was active

@spec sessions_page(filter(), keyword()) :: {[map()], DateTime.t() | nil}

sessions/2, plus the cursor for the next page: {rows, next_before}, where next_before is nil on the last page.

@spec sites(filter()) :: [String.t()]

Hosts that received traffic, for the site selector.

@spec slow_min_views() :: pos_integer()

Slowest paths by average server response time.

This comes free with page-view tracking — the plug already measured the response — and is often the most actionable table here: a page that is both popular and slow shows up in one query. Paths with fewer than three views are excluded, since one cold request would otherwise top the list.

@spec storage_stats() :: %{
  events: non_neg_integer(),
  events_estimated?: boolean(),
  rollup_days: non_neg_integer(),
  oldest: DateTime.t() | nil
}

Stored rows and the oldest retained timestamp — shown on the settings page so an operator can see what retention is actually doing.

The event count is exact below 100,000 rows and Postgres's planner estimate above that (events_estimated?: true): an exact count(*) over a large append-only table is a full scan, and this runs on every settings and Modules page load.

@spec timeseries(filter(), :hour | :day | :month) :: [map()]

Page views and visitors per time bucket, oldest first.

Empty buckets are filled in with zeros, so a chart doesn't have to reason about gaps. Each entry is %{bucket: DateTime.t(), pageviews: n, visitors: n}.

@spec top_campaigns(filter(), keyword()) :: [map()]

Top UTM campaigns.

@spec top_events(filter(), keyword()) :: [map()]

Custom events, ranked by occurrence.

@spec top_interactions(filter(), keyword()) :: [map()]

What visitors did, ranked: LiveView events by name, and the client script's clicks by kind and target ("outbound · github.com/acme"). Each row is %{label, name, target, pageviews: count, visitors}.

@spec top_paths(filter(), keyword()) :: [map()]

Most viewed paths. :offset pages through them (with :limit).

@spec top_referrers(filter(), keyword()) :: [map()]

Top referring sources, excluding internal navigation and direct traffic.

@spec top_utm_sources(filter(), keyword()) :: [map()]

Top UTM sources.