> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Data reference
> Metrics, breakdowns, refresh cadence, and limits for the Matomo data source in Adriel.
## Introduction
Matomo (formerly Piwik) is an open-source web analytics platform that can be self-hosted or used as Matomo Cloud. The connector queries the Matomo Reporting API for visitor traffic, behavior, and conversion data scoped to a single tracked site. The connector does not distinguish between self-hosted Matomo and Matomo Cloud — both are reached through the same Reporting API, and only the base URL differs.
As an analytics connector, session, event, and breakdown data are standardized so widgets can aggregate alongside ad-platform sources. To connect this data source, see [How to connect Matomo to Adriel](/data-sources/g-n/matomo/how-to-connect).
## Data refresh strategy
### Architecture data
Account structure — the Matomo instance and the list of tracked sites available to the supplied token — is resolved at connection time from the `MultiSites.getAll` report. The selected site ID is stored on the data source, and one data source corresponds to a single Matomo site.
### Reports data
Reports data is fetched **on demand**. Fresh data is requested from the Matomo Reporting API whenever a widget renders — there is no nightly snapshot or daily cache tier. Returned rows reflect the Matomo instance's current processing state, so performance on long date ranges depends on how the instance is configured to archive report data.
## Architecture levels
Matomo instance → Site (`idsite`) → Visit → Action / Goal
One Adriel data source maps to a single Matomo site. To report on multiple sites, create additional data sources.
## Date range limits
| Breakdown | Max range |
| --------- | --------- |
| Daily | 93 days |
| Weekly | 1 year |
The Matomo Reporting API itself accepts arbitrary date ranges. The caps above apply to the Daily and Weekly time groupings: when a query exceeds them, data outside the range may be truncated. Monthly, quarterly, and yearly groupings have no connector-side cap.
## Metrics
**How to read the columns**
Code style like `nb_visits` is the literal Matomo Reporting API field name. *Italic text* describes how a value is produced when it doesn't map cleanly to a single Matomo field or when it's computed by Adriel.
**Data type vocabulary**: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean.
### Users & sessions
| Metric | Description | Data type | API Key |
| --------------- | --------------------------------------------------------------------------------------------------------------- | --------- | ------------------ |
| Visits | Number of visits (30 minutes of inactivity is treated as a new visit). | Number | `nb_visits` |
| Unique visitors | Number of unique visitors. | Number | `nb_uniq_visitors` |
| Users | Number of unique active users (visitors with a known User ID). Set to zero when User ID tracking is not in use. | Number | `nb_users` |
### Engagement
| Metric | Description | Data type | API Key |
| ---------------- | --------------------------------------------------------------- | ---------- | ------------------ |
| Actions | Number of actions (page views, outlinks, and downloads). | Number | `nb_actions` |
| Max actions | Maximum number of actions in a single visit. | Number | `max_actions` |
| Sum visit length | Total time spent, in seconds. | Duration | `sum_visit_length` |
| Bounce count | Number of visits that bounced (viewed only one page). | Number | `bounce_count` |
| Bounce rate | Ratio of visits leaving the website after landing on this page. | Percentage | `bounce_rate` |
### Events & conversions
| Metric | Description | Data type | API Key |
| ------------------- | --------------------------------------- | --------- | ---------------------- |
| Goal conversions | Number of goal conversions. | Number | `nb_conversions` |
| Visits converted | Number of visits that converted a goal. | Number | `nb_visits_converted` |
| Goal revenue | Total revenue of goal conversions. | Currency | `revenue` |
| Events | Number of events. | Number | `nb_events` |
| Events with value | Number of events that had a value set. | Number | `nb_events_with_value` |
| Average event value | Average of event values. | Number | `avg_event_value` |
| Max event value | Maximum event value. | Number | `max_event_value` |
| Min event value | Minimum event value. | Number | `min_event_value` |
| Sum event value | Sum of event values. | Number | `sum_event_value` |
### Ecommerce
| Metric | Description | Data type | API Key |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------------- |
| Orders | Total number of ecommerce orders that contained this product SKU/name/category at least once. | Number | `orders` |
| Conversion rate | Orders (or abandoned carts) containing this product/category divided by visits on the product/category page. Appears only when ecommerce product/category page tracking is set up. | Percentage | `conversion_rate` |
| Revenue | Total revenue generated by product sales; excludes tax, shipping, and discount. | Currency | `revenue` |
| Quantity | Total number of products sold for each product SKU/name/category. | Number | `quantity` |
| Average quantity | Average quantity for this product/category. | Ratio | `avg_quantity` |
| Average price | Average revenue for this product/category. | Currency | `avg_price` |
| Abandoned carts | Total number of abandoned carts that contained this product SKU/name/category at least once. Set only when the request includes `&abandonedCarts=1`. | Number | `abandoned_carts` |
### Pages & screens
| Metric | Description | Data type | API Key |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------- |
| Hits | Number of views on this page. | Number | `nb_hits` |
| Entry visits | Number of visits that started on this page. | Number | `entry_nb_visits` |
| Entry actions | Number of page views for visits that started on this page. | Number | `entry_nb_actions` |
| Entry unique visitors | Number of unique visitors that started their visit on this page. | Number | `entry_nb_uniq_visitors` |
| Entry bounce count | Number of visits that started on this page and bounced. | Number | `entry_bounce_count` |
| Entry sum visit length | Time spent, in seconds, by visits that started on this page. | Duration | `entry_sum_visit_length` |
| Exit visits | Number of visits that finished on this page. | Number | `exit_nb_visits` |
| Exit unique visitors | Number of unique visitors that ended their visit on this page. | Number | `exit_nb_uniq_visitors` |
| Exit rate | Ratio of visits that do not view any other page after this page. | Percentage | `exit_rate` |
| Sum time spent | Total time spent on this page, in seconds. | Duration | `sum_time_spent` |
| Average time on page | Average time spent, in seconds, on this page. | Duration | `avg_time_on_page` |
| Sum daily unique visitors | Sum of daily unique visitors over the days in the period (Matomo does not process unique visitors across the full period). | Number | `sum_daily_nb_uniq_visitors` |
| Sum daily entry unique visitors | Sum of daily unique visitors that started their visit on this page. | Number | `sum_daily_entry_nb_uniq_visitors` |
## Breakdowns
**How to read the columns**
For platform breakdowns, the API Key is the Matomo Reporting API method that supplies the values (e.g. `UserCountry.getCountry`). *Italic text* describes a value produced by Adriel rather than returned directly by Matomo.
### Geography
| Breakdown | Description | API Key |
| -------------------- | ---------------------------------- | ------------------------------ |
| Continent | Visitor continent. | `UserCountry.getContinent` |
| Country | Visitor country. | `UserCountry.getCountry` |
| Region | Visitor region. | `UserCountry.getRegion` |
| City | Visitor city. | `UserCountry.getCity` |
| Web-browser language | Language of the visitor's browser. | `UserLanguage.getLanguage` |
| Language code | Browser language code. | `UserLanguage.getLanguageCode` |
### Devices & software
| Breakdown | Description | API Key |
| ------------------------- | ------------------------------------------------- | ------------------------------------- |
| Device type | Device category (desktop, mobile, tablet, etc.). | `DevicesDetection.getType` |
| Device brand | Device brand. | `DevicesDetection.getBrand` |
| Device model | Device model. | `DevicesDetection.getModel` |
| Screen resolution | Visitor screen resolution. | `Resolution.getResolution` |
| Configurations | Combined OS / browser / resolution configuration. | `Resolution.getConfiguration` |
| Operating system versions | Operating system versions. | `DevicesDetection.getOsVersions` |
| Operating system families | Operating system families. | `DevicesDetection.getOsFamilies` |
| Browsers | Browser names. | `DevicesDetection.getBrowsers` |
| Browser version | Browser versions. | `DevicesDetection.getBrowserVersions` |
| Browser engines | Browser rendering engines. | `DevicesDetection.getBrowserEngines` |
| Browser plugins | Browser plugins detected. | `DevicePlugins.getPlugin` |
### Visitor behavior
| Breakdown | Description | API Key |
| ------------------------------- | ------------------------------------------ | --------------------------------------------------- |
| User IDs | Visitors identified by User ID. | `UserId.getUsers` |
| Users flow | Path visitors take through the site. | `UsersFlow.getUsersFlowPretty` |
| Returning visits | Returning-visitor frequency. | `VisitFrequency.get` |
| Length of visits | Distribution of visits by duration. | `VisitorInterest.getNumberOfVisitsPerVisitDuration` |
| Pages per visit | Distribution of visits by number of pages. | `VisitorInterest.getNumberOfVisitsPerPage` |
| Visits by visit number | Visits grouped by visit count. | `VisitorInterest.getNumberOfVisitsByVisitCount` |
| Visits by days since last visit | Visits grouped by recency. | `VisitorInterest.getNumberOfVisitsByDaysSinceLast` |
| Visits by day of the week | Visits grouped by weekday. | `VisitTime.getByDayOfWeek` |
| Visits per local time | Visits by the visitor's local hour. | `VisitTime.getVisitInformationPerLocalTime` |
| Visits per hour (site timezone) | Visits by hour in the site's timezone. | `VisitTime.getVisitInformationPerServerTime` |
### Pages & actions
| Breakdown | Description | API Key |
| ---------------------- | ----------------------------------- | ---------------------------- |
| Actions – main metrics | Overview of action metrics. | `Actions.get` |
| Page URLs | Page URLs of actions. | `Actions.getPageUrls` |
| Page titles | Page titles. | `Actions.getPageTitles` |
| Entry pages | First page in a visit. | `Actions.getEntryPageUrls` |
| Entry page titles | Title of the first page in a visit. | `Actions.getEntryPageTitles` |
| Exit pages | Last page in a visit. | `Actions.getExitPageUrls` |
| Exit page titles | Title of the last page in a visit. | `Actions.getExitPageTitles` |
| Downloads | Files downloaded. | `Actions.getDownloads` |
| Outlinks | Outbound links clicked. | `Actions.getOutlinks` |
| Performance overview | Page performance timings. | `PagePerformance.get` |
Several page and action breakdowns above also have an **"Exact"** variant (for example, Exact Page URLs, Exact Entry pages, Exact Event Names) that returns a flat, non-hierarchical list of the same values. The Exact variants call the same Matomo methods with `flat=1&expanded=1`.
### Site search
| Breakdown | Description | API Key |
| ----------------------------------- | --------------------------------------- | ------------------------------------------ |
| Site search keywords | Keywords searched on the site. | `Actions.getSiteSearchKeywords` |
| Search categories | Site-search categories. | `Actions.getSiteSearchCategories` |
| Search keywords with no results | Searches that returned no results. | `Actions.getSiteSearchNoResultKeywords` |
| Pages following a site search | Pages viewed after a site search. | `Actions.getPageUrlsFollowingSiteSearch` |
| Page titles following a site search | Page titles viewed after a site search. | `Actions.getPageTitlesFollowingSiteSearch` |
### Events
| Breakdown | Description | API Key |
| ---------------- | ---------------------- | -------------------- |
| Event categories | Event category values. | `Events.getCategory` |
| Event actions | Event action values. | `Events.getAction` |
| Event names | Event name values. | `Events.getName` |
### Content
| Breakdown | Description | API Key |
| ------------- | ---------------------- | --------------------------- |
| Content name | Tracked content name. | `Contents.getContentNames` |
| Content piece | Tracked content piece. | `Contents.getContentPieces` |
### Traffic acquisition
| Breakdown | Description | API Key |
| -------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
| Referrers overview | Summary of referrer types. | `Referrers.get` |
| Channel type | Referrer type (direct, search, website, social, campaign). | `Referrers.getReferrerType` |
| All channels | All referrer channels combined. | `Referrers.getAll` |
| Websites | Referring websites. | `Referrers.getWebsites` |
| Social networks | Referring social networks. | `Referrers.getSocials` |
| Search engines | Referring search engines. | `Referrers.getSearchEngines` |
| Keywords (including not defined) | Search keywords, including undefined. | `Referrers.getKeywords` |
| Combined keywords | Keywords from connected search-engine performance data. | `SearchEngineKeywordsPerformance.getKeywords` |
| Web keywords on Google | Google web-search keywords. | `SearchEngineKeywordsPerformance.getKeywordsGoogleWeb` |
### Campaigns
| Breakdown | Description | API Key |
| ------------------------ | ------------------------------------ | --------------------------------------------- |
| Campaign names | Marketing campaign names. | `MarketingCampaignsReporting.getName` |
| Campaign keywords | Campaign keywords. | `MarketingCampaignsReporting.getKeyword` |
| Campaign sources | Campaign sources. | `MarketingCampaignsReporting.getSource` |
| Campaign mediums | Campaign mediums. | `MarketingCampaignsReporting.getMedium` |
| Campaign source – medium | Combined campaign source and medium. | `MarketingCampaignsReporting.getSourceMedium` |
| Campaign contents | Campaign content values. | `MarketingCampaignsReporting.getContent` |
| Campaign IDs | Campaign identifiers. | `MarketingCampaignsReporting.getId` |
| Campaign groups | Campaign groups. | `MarketingCampaignsReporting.getGroup` |
| Campaign placements | Campaign placements. | `MarketingCampaignsReporting.getPlacement` |
### Ecommerce & goals
| Breakdown | Description | API Key |
| --------------------------------------- | --------------------------------- | -------------------------------- |
| Ecommerce orders | Ecommerce order goal report. | `Goals.get` |
| Ecommerce orders – visits to conversion | Visits before an ecommerce order. | `Goals.getVisitsUntilConversion` |
| Ecommerce orders – days to conversion | Days before an ecommerce order. | `Goals.getDaysToConversion` |
| Abandoned carts | Abandoned-cart goal report. | `Goals.get` |
| Abandoned carts – visits to conversion | Visits before cart abandonment. | `Goals.getVisitsUntilConversion` |
| Abandoned carts – days to conversion | Days before cart abandonment. | `Goals.getDaysToConversion` |
| Product name | Ecommerce product name. | `Goals.getItemsName` |
| Product SKU | Ecommerce product SKU. | `Goals.getItemsSku` |
### Sites
| Breakdown | Description | API Key |
| ------------------------ | ------------------------------------- | ------------------- |
| All websites dashboard | Overview across all accessible sites. | `MultiSites.getAll` |
| Single website dashboard | Overview for the connected site. | `MultiSites.getOne` |
| Visits summary | Visit-summary overview. | `VisitsSummary.get` |
Matomo instances can define **Custom Reports**. When present, these appear as additional breakdowns (for example, Klaviyo Campaigns, Google Ads Traffic Over Time, Revenue Over Time), all served by `CustomReports.getCustomReport`. Because they are configured per Matomo instance, the exact list varies by account.
### Time & date grouping
Adriel groups Matomo's results into these standard time views for reporting alongside other connectors.
| Breakdown | Description |
| ------------------- | ----------------------------------------------------------------------- |
| No Grouping | No temporal grouping applied. |
| Auto Time Breakdown | Automatically picks the best granularity for the date range. |
| Daily | Split reports by day. Limited to a maximum of 93 days. |
| Weekly (Start: Mon) | Split reports by week, starting Monday. Limited to a maximum of 1 year. |
| Monthly | Split reports by calendar month. |
| Quarterly | Split reports by calendar quarter. |
| Yearly | Split reports by calendar year. |
**Partial-period rows**: when the "from" and "to" filters do not align with the start and end of a period (week, month, quarter, or year), the entire period is still displayed. The "from" and "to" filters continue to apply to the Total row.
### Other Adriel breakdowns
These breakdowns are added by Adriel and are available across analytics connectors.
| Breakdown | Description |
| --------------- | ------------------------------------- |
| Channel | Groups results by channel (platform). |
| Datasource Name | Name of the Adriel data source. |
## Limitations
Based on the current connector, Matomo has:
* **One site per data source** — a connection scopes to a single `idsite`. Reporting on multiple sites requires additional data sources.
* **Live queries with no cache** — every widget render issues a fresh call to the Matomo Reporting API, so performance on long date ranges depends on the Matomo instance's archive configuration.
* **A 93-day cap on the Daily breakdown and a 1-year cap on the Weekly breakdown** — data outside these ranges may be truncated.
* **No deleted elements** — the connector does not surface data for deleted items.
* **User ID dependency** — the Users metric (`nb_users`) is zero unless the site tracks visitors with User IDs.
* **Ecommerce tracking dependency** — several ecommerce metrics appear only when Matomo product/category page tracking is configured; abandoned-cart metrics require the `abandonedCarts` request flag.
* **Cross-connector blending** — Matomo report data may require blend settings before it can be combined with other data sources in the same widget.
## API references
* [Matomo Reporting API](https://developer.matomo.org/api-reference/reporting-api)
* [Matomo Reporting API metadata (`API.getProcessedReport`)](https://developer.matomo.org/api-reference/reporting-api-metadata)
* [Matomo API authentication (`token_auth`)](https://developer.matomo.org/guides/authentication-in-api)
## See also
* [How to connect Matomo](/data-sources/g-n/matomo/how-to-connect) (paired how-to)
* [Google Analytics 4 data reference](/data-sources/g-n/google-analytics-4/data-reference) — for the alternative analytics connector
* [Piano Analytics data reference](/data-sources/o-z/piano-analytics/data-reference) — for another analytics connector