traffic-report

Traffic Report

Generate a comprehensive traffic report for a Matomo-tracked site. Default period is last 7 days unless specified in $ARGUMENTS.

Site selection

If $ARGUMENTS contains a site ID or name, use that. If the conversation already has a site in context, use that. Otherwise, call matomo_list_sites, present a short numbered list (ID, name, URL), and ask which site to analyze. Do not proceed until a site is selected.

Steps

1. Visits summary using matomo_get_visits for the requested period

2. Real-time snapshot using matomo_get_live_counters (last 30 minutes)

3. Top pages using matomo_get_top_pages with limit 10

4. Entry pages using matomo_get_entry_pages with limit 5 to show where visitors land

5. Traffic sources using matomo_get_search_engines and matomo_get_ai_assistants with limit 5 each

6. Device segment using matomo_get_devices for the same period to show the desktop vs mobile split. If the user asked for a mobile-only report, pass device: "mobile" to steps 1, 3, 4 instead and note that the whole report is scoped to smartphone+tablet+phablet.

7. Present as a report with sections:

   • Key metrics: visits, unique visitors, actions, bounce rate, avg time on site
   • Currently online (live counters)
   • Top pages (table: page, visits, avg time, bounce rate)
   • Where visitors come from (search engines, AI assistants)
   • Top landing pages
   • Device split (desktop vs mobile share)

Keep the report concise and highlight anything unusual (high bounce rates, traffic spikes, etc.).

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 and does NOT need segment archiving. For mobile: {siteId, period, date, device: "mobile"} returns {visits, byDevice, byCountryTop10}.
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 — the UI uses the user's permissions, not the token:

   <matomo-host>/index.php?module=CoreHome&action=index
     &idSite=<id>&period=<period>&date=<date>
     &segment=deviceType%3D%3Dsmartphone%2CdeviceType%3D%3Dtablet%2CdeviceType%3D%3Dphablet
   

4. Longer-term fix: ask the Matomo admin to grant process_new_segment on the token or pre-archive common segments.