page-events-analysis

Page Events Analysis

Analyze page views and events for specific URL patterns, then cross-reference them to calculate usage rates. This answers questions like "how many people used feature X on pages Y".

Gather Parameters

Ask the user for (or infer from context):

1. Site ID - the Matomo site to query
2. URL pattern - regex to filter pages (e.g. guidelines-epc|guidelines-pct)
3. Event filter - the event name or action to cross-reference (e.g. Toggle Show Modifications)
4. Date range - start and end dates (default: last 30 days from today)
5. Device filter (optional) - desktop, mobile, smartphone, tablet, or phablet if the user asks about a specific device slice (e.g. "how many mobile users toggled X")

Execution Steps

1. Fetch page views

Call matomo_search_pages with:

• siteId: the site ID
• urlPattern: the URL pattern
• period: range when the user gave start/end dates, otherwise month for long windows and day for short ones
• date: comma-separated start,end range when period=range (e.g. 2026-02-01,2026-02-28)
• device: pass through if the user asked for a device slice

Sum up nb_visits (unique visitors) and nb_hits (page views) across all matching pages. Keep monthly totals if the range spans multiple months.

2. Fetch event counts

Call matomo_search_events with:

• siteId: the site ID
• filterPattern: the event filter
• dimension: name (to see specific event values like on/off toggles)
• period, date, device: same as above

Sum up nb_events across all matching events. Keep monthly totals.

3. Calculate usage rate

usage_rate = (total_events / total_page_views) * 100

If both on/off event variants exist (e.g. "Toggle Show Modifications On" and "Toggle Show Modifications Off"), report them separately and combined.

4. Present findings

Provide a summary with:

Key figures:

• Total page views (hits) and unique visitors
• Total events (broken down by variant if applicable)
• Overall usage rate %

Monthly breakdown table:

Month	Page Views	Unique Visitors	Events	Usage Rate
...	...	...	...	...
Total	...	...	...	...%

Observations:

• Note any trends (increasing/decreasing adoption)
• Flag months with unusual spikes or drops
• If usage rate is very low or very high, call it out

Fallback when segments return zero

If a device-filtered call comes back with all-zero metrics while the same query without device returns normal numbers, the Matomo server is refusing to aggregate the segment for this API token (it lacks process_new_segment or the segment isn't pre-archived). Do not claim "no mobile traffic" — that's almost never the real answer.

Try these in order:

1. Switch to matomo_count_visits_by_segment. It uses the Live API under the hood (no archiving required) and accepts the same device shortcut plus an optional urlPattern for the page filter. For per-URL mobile slicing: {siteId, period, date, device: "mobile", urlPattern: "bulletin/download"} Returns {visits, byDevice, byCountryTop10, actionHitsOnPattern}. For per-language breakdown, call matomo_get_last_visits with the same segment and iterate actionDetails[].url client-side (strip ISO lang prefix with regex /^/([a-z]{2})/...).
2. Check matomo_list_segments to find saved segments on the instance. Any segment with auto_archive=1 is pre-archived and will always return real numbers when you reference its definition string in segment.
3. Open the Matomo UI in a logged-in browser session as a last resort.
4. Longer-term fix: ask the Matomo admin to grant process_new_segment on the token or pre-archive common segments.