Matomo and CodeWords: owning the analytics data

Matomo is chosen for one reason above all others: the data is yours. Self-hosted, it sits in a database you administer, which removes the sampling, thresholding, and retention limits that shape what other analytics platforms will tell you.

That ownership is also the work. Nobody else is managing the archiving, the database growth, or the upgrades, and an installation left alone degrades in ways that are entirely preventable and entirely your responsibility.

What we'll cover

• Self-hosted or cloud
• Archiving, which decides everything
• What Matomo reaches
• Connecting it to CodeWords
• Seven automations worth building
• Consent-free tracking, honestly
• The database you can query directly
• Retention, which nobody sets until it hurts
• Building it so it survives
• Limits worth knowing about
• What to build first
• Frequently asked questions

Self-hosted or cloud

The choice changes what automation is available and what you are responsible for.

Self-hosted gives you database access, which is the single largest capability difference — arbitrary SQL over your own analytics data.

Self-hosted means you run the archiving, the database maintenance, the upgrades, and the backups.

Cloud removes the operations and keeps the reporting API, which covers most reporting needs.

Raw log access differs. Self-hosted, you have everything. Cloud, you have what the API exposes, which is a great deal and not the same thing.

Data residency is yours to choose when self-hosting, which is frequently the reason for choosing it.

Most of what follows applies to both. The database section applies only to self-hosted, and it is worth knowing what you gain by being there.

Archiving, which decides everything

Matomo stores raw tracking data and pre-aggregates it into reports. That aggregation is archiving, and it is the thing people get wrong.

Browser-triggered archiving is the default and is wrong for any real traffic. It means somebody opening a report triggers aggregation, which makes the interface slow and occasionally times out.

Run archiving from the console on a schedule — this is the single most impactful change to a self-hosted installation and it is one cron entry.

Disable browser archiving once the scheduled job exists, or you have both.

Archiving time grows with traffic and with the number of segments, and a segment that has to be archived separately multiplies the work.

A failed archive is silent. Reports simply show stale numbers, which looks like a quiet week rather than a broken job.

Monitoring that archiving ran and how long it took is the first automation worth building on a self-hosted installation, and it is rarely in place.

What Matomo reaches

The Reporting API covers every report available in the interface, by site, period, and segment, in several formats.

The Tracking API accepts events from servers, which is how you track things a browser cannot see.

Segments can be defined and applied to any report, which is where most analytical depth lives.

Goals and ecommerce reporting, including per-order detail.

Site management — adding and configuring sites — which suits anything provisioning per customer.

User and permission management, for anything onboarding people automatically.

Raw visit logs are available, which distinguishes Matomo from platforms that only expose aggregates.

The database directly, when self-hosted, which is the capability nothing else on this list matches.

Connecting it to CodeWords

CodeWords connects to more than 3,000 integrations, and the connection is made once and reused.

1. Open CodeWords and start a new automation.
2. Describe what should happen in plain language to Cody, the automation builder: which site, which report or segment, and where the answer goes.
3. Authorize the connection with an API token for a user holding view access to the relevant sites — read-only for anything that only reports.
4. Describe the exceptions: an archive that has not run, a report returning nothing, a figure outside a plausible range.
5. Run it against a period where you already know the answer.

You describe the outcome; Cody builds it, connects it, and deploys it. The free plan covers light use, with Pro at $39 per month and Business at $100 per month as usage grows; details are on the pricing page.

Seven automations worth building

Archiving health monitoring. Whether the job ran, how long it took, and whether it is trending longer. The first thing to build on self-hosted and almost never present.

Scheduled reports with comparison. The numbers somebody checks anyway, delivered with the movement stated rather than the level.

Tracking health monitoring. Goals that have stopped converting, pages that have stopped receiving traffic, a site that has gone quiet — all of which mean broken instrumentation more often than they mean a business change.

Server-side event tracking. Conversions, payments, and background processes sent through the Tracking API, which is where accuracy matters and browsers cannot help.

Cross-site reporting for anybody running several sites, since the interface reports per site and the question is usually across them.

Database growth and retention reporting, because raw log tables grow steadily and an installation with no retention policy eventually becomes slow.

Site and user provisioning, for agencies and multi-tenant products where a new customer means a new site and the right permissions.

Consent-free tracking, honestly

Matomo is frequently chosen because a particular configuration may be exempt from consent requirements in some jurisdictions, and it is worth being precise about what that involves.

The exemption is configuration-dependent, not a property of the product. Anonymising addresses, disabling cookies, limiting retention, and honouring do-not-track are all part of it.

Anonymised measurement loses accuracy. Cookieless tracking cannot follow a visitor across sessions reliably, so returning visitor and multi-session attribution figures are approximations.

Your regulator's view governs, and guidance differs by jurisdiction and changes.

It is a legal question, not a technical one. A page like this cannot tell you whether your configuration is compliant, and the honest answer is that it depends on where you are and what you have configured.

Verify the configuration automatically — anonymisation on, retention set, the settings you were told to apply still applied. Settings drift after upgrades and after somebody investigates something.

The database you can query directly

Self-hosted only, and it is the reason a lot of teams are self-hosted.

No sampling and no thresholding. You are querying the underlying data, so small segments are visible and totals are exact.

Join against your own data. Analytics against orders, customers, or support history is a query rather than an exercise in reconciliation.

Query a replica, not the primary, since analytical queries compete with tracking writes and tracking is the part you cannot afford to slow down.

Know the schema is internal. Table structures can change between versions, so queries written against them are maintenance you have accepted.

Prefer the API where it answers the question, and go to the database for what it cannot — which is joins, exact long-tail detail, and anything the report set does not cover.

Retention, which nobody sets until it hurts

Raw visit and action tables grow with every visit and they are never cleaned up unless somebody decides they should be.

Decide how long you need raw data. Aggregated reports remain after raw logs are deleted, so a short raw retention and indefinite reports is a perfectly reasonable position.

Deleting old logs reclaims space and speeds up everything touching those tables, including archiving.

Run the deletion off-peak and in batches, since a first deletion over years of accumulated data is a substantial operation.

Check the reports you rely on survive it. Anything recomputed from raw data cannot be recomputed once the raw data is gone, so archive first and delete afterwards.

Report the growth rate, not just the size, so the conversation happens before the disk is full rather than during an outage.

Back up before the first deletion. It is irreversible, and the first run removes far more than every subsequent one.

Building it so it survives

Check the archive is current before reporting a number, or you will report stale figures confidently.

Use read-only credentials for reporting, both for the API and for any database access.

Paginate raw log queries, which can return very large result sets.

Version-check anything touching the database schema, since upgrades can change it.

Report the outcome. What ran, for which period, and whether the underlying archive was fresh.

Limits worth knowing about

Archiving is the performance constraint, and the number of segments multiplies it.

Raw log tables grow steadily, and without a retention policy the database becomes the problem.

Some plugins are premium or version-dependent, so a report available in one installation may not exist in another.

API rate limiting depends on your own server when self-hosted, which means your automation's load is your problem rather than somebody else's.

Upgrades require attention, including database migrations, which is the cost of ownership.

What to build first

Archiving health monitoring: whether the scheduled archive ran, how long it took, and whether that duration is trending upwards. It is a small automation, it needs read access only, and a failed archive is silent — reports keep rendering, showing numbers that stopped updating days ago.

Two habits make the difference. Alert on the archive not having run rather than only on it failing, since the common case is a cron job that quietly stopped. And track the duration trend, because archiving time creeping up is the early warning that the installation needs attention before it starts timing out.

Frequently asked questions

Why is the Matomo interface slow?

Almost always browser-triggered archiving, which aggregates on demand when somebody opens a report. Run archiving from the console on a schedule and disable the browser trigger — it is one cron entry and it is the single largest improvement available.

Do I need consent to use Matomo?

It depends on your configuration and your jurisdiction, and it is a legal question rather than a technical one. Certain configurations may be exempt in some places; that exemption depends on anonymisation, cookie use, retention, and honouring do-not-track being configured correctly.

Why did my report stop updating?

The archive probably stopped running. It fails silently — reports still render, with numbers that stopped moving. Monitoring that the job ran is the fix, and it is the reason it is the first thing worth automating.

Can I query the database directly?

When self-hosted, yes, and it is the main capability advantage: no sampling, no thresholding, and joins against your own data. Use a replica, and accept that the schema is internal and can change between versions.

Is self-hosted or cloud better?

Cloud if you want the reporting without operating anything. Self-hosted if you need database access, full raw data, or control over data residency — and are prepared to own archiving, growth, and upgrades.

How accurate is cookieless tracking?

Less accurate for anything spanning sessions. Single-visit measurement holds up; returning visitors and multi-session attribution become approximations. That is the trade for the privacy configuration, and it is worth stating on reports rather than presenting the figures as exact.

What should I track server-side?

Anything that must be accurate — conversions, payments, and background processes — through the Tracking API. Browser-side measurement is incomplete by nature, and the events that matter commercially are exactly the ones worth measuring where nothing can block them.

How long should we keep raw visit data?

Long enough to recompute anything you might need, which for most teams is months rather than years. Aggregated reports survive raw log deletion, so short raw retention with indefinite reports is a reasonable and much cheaper position.

What should I check before deleting old logs?

That everything you rely on has been archived, since anything recomputed from raw data cannot be recomputed afterwards. Back up first, run it off-peak in batches, and expect the first run to be far larger than later ones.

Related reading

• Plausible and CodeWords
• PostHog and CodeWords
• CodeWords integrations and templates