> For the complete documentation index, see [llms.txt](https://docs.quanti.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.quanti.io/connectors/analytics-connectors/matomo.md).

# Matomo

<a href="https://dbdiagram.io/e/689b41c01d75ee360a3d6e88/689b474e1d75ee360a3e98a0" class="button primary" data-icon="table-tree">Prebuilt reports and definition</a>

***

## Prerequisites

To connect Matomo to QUANTI:, you need a [Matomo](https://fr.matomo.org/login/) account.

***

## Setup instructions

### Find your Auth token

1. Go to Matomo settings Settings Cog Icon > Personal > Security.
2. At the bottom of the page, click on Create new token.<br>

   <figure><img src="/files/N5bWZ3NEINAAXVhbvpKq" alt=""><figcaption></figcaption></figure>
3. Confirm your account password.
4. Enter the purpose for this token.
5. Choose if the token should only be valid for secure requests (Matomo 5 and newer).
6. Click on Create new token.

### Connector configuration

1. Authentication
   1. Enter the Auth token you retrieved in the previous step.
   2. Enter the Matomo URL that allows you to access your reports. This should be in the form: <https://data.yourwebsite.com>.
2. Connector information
   1. Connector Name: Name your connector. It must be unique.
   2. Dataset ID: Define the ID of the dataset. It must not already exist, as it will be created and data will be sent there.
3. Select your Advertiser Id: Choose your Advertiser ID.
4. Select the pre-built reports you want to synchronize, and/or create your own custom reports. To help you configure custom reports, refer to the **Custom reports** chapter below.

***

## Prebuilt reports

### Visitor

**visitor\_country**: Website visits, user actions and conversions segmented by the visitor's country. Dimensions: date, country. Metrics: visits, users, actions, bounces, conversions, converted\_visits, total\_visit\_length, revenue.

**visitor\_device\_type**: Website activity broken down by device type (desktop, mobile, tablet). Dimensions: date, device\_type. Metrics: visits, users, actions, bounces, conversions, converted\_visits, total\_visit\_length, revenue.

**visitor\_language**: Engagement metrics segmented by the visitor's browser language. Dimensions: date, language. Metrics: visits, users, actions, bounces, converted\_visits, total\_visit\_length, revenue.

***

### Behaviour

**behaviour\_page**: Page-level engagement — entrances, exits, pageviews and time spent per URL. Dimensions: date, page\_title, page\_url. Metrics: pageviews, entrances, entry\_actions, entry\_bounces, exits, total\_time\_spent, visits\_following\_search.

**behaviour\_event**: Event tracking by category — event counts, unique events and total/average event value. Dimensions: date, event\_category. Metrics: events, unique\_events, event\_value\_sum, event\_value\_avg.

***

### Acquisition

**acquisition\_campaign**: Visitor metrics grouped by marketing campaign name. Dimensions: date, campaign\_name. Metrics: visits, users, actions, bounces, conversions, converted\_visits, total\_visit\_length, revenue.

**acquisition\_channel\_type**: Website performance aggregated by high-level marketing channel (organic, paid, social, direct…). Dimensions: date, channel\_type. Metrics: visits, users, actions, bounces, conversions, converted\_visits, total\_visit\_length, revenue.

**acquisition\_referrer**: Visits and conversions by referring source, type and URL. Dimensions: date, referrer, referrer\_type. Metrics: visits, users, actions, bounces, conversions, converted\_visits, total\_visit\_length, revenue.

***

```mermaid
erDiagram
    visitor_country {
        DATE    _quanti_date PK
        STRING  country PK
        DATE    date
        INTEGER visits
        INTEGER users
        INTEGER actions
        INTEGER bounces
        INTEGER conversions
        FLOAT   revenue
        STRING  website_id
    }
    visitor_device_type {
        DATE    _quanti_date PK
        STRING  device_type PK
        DATE    date
        INTEGER visits
        INTEGER users
        INTEGER actions
        INTEGER bounces
        INTEGER conversions
        FLOAT   revenue
        STRING  website_id
    }
    visitor_language {
        DATE    _quanti_date PK
        STRING  language PK
        DATE    date
        INTEGER visits
        INTEGER users
        INTEGER actions
        INTEGER bounces
        FLOAT   revenue
        STRING  website_id
    }
    behaviour_page {
        DATE    _quanti_date PK
        STRING  page_title PK
        STRING  page_url PK
        DATE    date
        INTEGER pageviews
        INTEGER entrances
        INTEGER exits
        INTEGER total_time_spent
        STRING  website_id
    }
    behaviour_event {
        DATE    _quanti_date PK
        STRING  event_category PK
        DATE    date
        INTEGER events
        INTEGER unique_events
        FLOAT   event_value_sum
        FLOAT   event_value_avg
        STRING  website_id
    }
    acquisition_campaign {
        DATE    _quanti_date PK
        STRING  campaign_name PK
        DATE    date
        INTEGER visits
        INTEGER users
        INTEGER conversions
        FLOAT   revenue
        STRING  website_id
    }
    acquisition_channel_type {
        DATE    _quanti_date PK
        STRING  channel_type PK
        DATE    date
        INTEGER visits
        INTEGER users
        INTEGER conversions
        FLOAT   revenue
        STRING  website_id
    }
    acquisition_referrer {
        DATE    _quanti_date PK
        STRING  referrer PK
        STRING  referrer_type PK
        DATE    date
        INTEGER visits
        INTEGER users
        INTEGER conversions
        FLOAT   revenue
        STRING  website_id
    }
```

***

<a href="https://dbdiagram.io/e/689b41c01d75ee360a3d6e88/689b474e1d75ee360a3e98a0" class="button primary" data-icon="table-tree">Prebuilt reports and definition</a>

***

## Custom reports

Matomo custom reports let you query any endpoint of the [Matomo Reporting API](https://developer.matomo.org/api-reference/reporting-api) and bring the result directly into your data warehouse.

#### Find available methods and fields

Each custom report is built around a **Matomo API method** (e.g. `VisitsSummary.get`, `Events.getCategory`). The method determines which fields are returned.

The reference for all available methods and their fields is the official Matomo Reporting API documentation: 👉 [developer.matomo.org/api-reference/reporting-api](https://developer.matomo.org/api-reference/reporting-api)

{% hint style="info" %}
**Use an AI assistant to speed up the configuration.** Rather than browsing the full API reference manually, describe the report you want to reproduce — as you see it in the Matomo interface — to an AI assistant (Claude, ChatGPT…). For example:

> *"I want to build a custom Matomo report showing event categories with the number of events and their total value. What API method and fields should I use in the QUANTI JSON format `{ "report": "", "flat": "1", "fields": "" }` ?"*

The AI will identify the correct `report` value and the exact `fields` string for you.
{% endhint %}

#### Configure the custom report

In QUANTI, at the **Select pre-built reports** step, click **Add custom report**. Fill in the following JSON:

```json
{
  "report": "",
  "flat": "1",
  "fields": ""
}
```

* **`report`** *(required)*: The Matomo API method name (e.g. `"VisitsSummary.get"`, `"Events.getCategory"`)
* **`flat`**: Set to `"1"` to flatten nested JSON structures — recommended for most reports
* **`fields`** *(optional)*: Comma-separated list of field names to retrieve. If omitted, all fields returned by the method are ingested — useful for a first run to discover what arrives in BigQuery

#### Common report examples

| Report           | `report` value              | Key `fields`                                                         |
| ---------------- | --------------------------- | -------------------------------------------------------------------- |
| Visit summary    | `VisitsSummary.get`         | `nb_visits,nb_uniq_visitors,nb_actions,bounce_rate,avg_time_on_site` |
| Event categories | `Events.getCategory`        | `label,nb_events,sum_event_value,avg_event_value`                    |
| Campaigns        | `Referrers.getCampaigns`    | `label,nb_visits,nb_actions,bounce_rate,revenue`                     |
| Channel types    | `Referrers.getReferrerType` | `label,nb_visits,nb_actions,avg_time_on_site,bounce_rate`            |

#### Map your fields (Schema)

After configuring the query, the **Schema** step lets you define how fields are stored in your data warehouse:

* Set the **field type** (STRING, INTEGER, FLOAT, DATE…) for each field
* Check **Unique identifiers** to mark dimension fields as part of the primary key (e.g. `date`, `label`, `website_id`) — they collectively form the unique identifier of each row

Once all fields are mapped, click **Save** to create the custom report table.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.quanti.io/connectors/analytics-connectors/matomo.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.