Matomo integration
Matomo is on the map, not in the product yet.
We read traffic and referrer reports from your Matomo instance, the GA4 alternative for privacy-first sites.
How it works
Matomo connects with a token_auth credential against your instance, whether that is Matomo Cloud or a server you run yourself. Through the Reporting API we pull traffic and referrer reports per published URL, batching calls with bulk requests so even a large content library syncs without hammering your instance. The result is the same per-page measurement GA4 customers get, from the analytics platform you chose for privacy reasons.
In the crawl, opportunity, write, publish, measure loop, Matomo is the measure step for teams who deliberately do not run Google Analytics. Published pages are judged on the visits and referrers your own instance records, so the opportunity engine learns which content earns traffic without your visitor data touching a third party it was never supposed to touch.
Best forPrivacy-focused teams running Matomo, cloud or self-hosted, who want per-page measurement without Google Analytics.
Setup, step by step
- In Matomo, create an auth token under your user's security settings, ideally on a user with view-only access.
- Paste your instance URL and the token into SearchHandled's Matomo connector.
- Run the connection test, which confirms the instance is reachable and the token can read reports.
- Pick the Matomo site ID that matches the site we publish to.
- Review the first traffic pull, which backfills recent per-page reports into your dashboard.
Best practices
Create the token on a view-only user
A token_auth carries the permissions of the user it belongs to across the whole instance. Creating it on a user with view-only access means the credential we hold can read reports and nothing more.
Keep your instance reasonably current
Self-hosted Matomo versions vary widely, and older releases differ in API behavior. Staying within a recent release keeps the Reporting API responses predictable and the sync clean.
Expect batched pulls, not a live feed
We use Matomo's bulk request support to fetch many page reports in few calls on a schedule. That keeps load on your instance light, which matters most when you host it yourself.
Tell us if the instance moves
Migrations to a new domain or from self-hosted to cloud change the instance URL and invalidate the old setup. Update the connector when you move, and the sync resumes without gaps.
Known issues
What practitioners actually report, from official docs, issue trackers, and community forums.
Self-hosted instances vary in version and uptime
A self-hosted Matomo can run an old version, sit behind strict firewalls, or simply be down when a sync runs, so responses differ from instance to instance.
How we handle itOur client handles errors defensively, retries transient failures, and reports a persistently unreachable instance in your dashboard instead of failing silently or guessing at data.
developer.matomo.org
The auth token is instance-wide
token_auth is not scoped to a single site or endpoint; it grants whatever its user can do across the instance, which is broader than one integration needs.
How we handle itWe store the token encrypted, use it only for read-only Reporting API calls, and recommend creating it on a view-only user so the credential itself cannot write anything.
developer.matomo.org
Questions teams ask
- Does this work with self-hosted Matomo or only Matomo Cloud?
Both. You give us the instance URL and a token, and the Reporting API works the same either way. Self-hosted instances just need to be reachable from the internet for the sync to run.
- Can SearchHandled change anything in our Matomo?
We only call the Reporting API to read data. Creating the token on a view-only user makes that a hard guarantee, which is why we recommend it during setup.
- What if our instance is down during a sync?
The sync retries and picks up where it left off once the instance is back. A prolonged outage is flagged in your dashboard, and no partial or guessed data enters your reports.
Not connectable yet
Start with the plan, not the connector.
Build a Growth Map from your site to see the work itself. Approved pages can leave through the export or the webhook today, and telling us Matomo matters moves it up the rollout.