Matomo Python API Docs | dltHub

Matomo is a web analytics platform that provides a Reporting HTTP API to request analytics reports (visits, actions, referrers, goals, etc.) in JSON, XML, CSV and other formats. The REST API base URL is https://{your-matomo-domain}/ and All requests that require access use a token_auth query parameter (or POST body) for authentication..

dlt is an open-source Python library that handles authentication, pagination, and schema evolution automatically. dlthub provides AI context files that enable code assistants to generate production-ready pipelines. Install with uv pip install "dlt[workspace]" and start loading Matomo data in under 10 minutes.

---

What data can I load from Matomo?

Here are some of the endpoints you can load from Matomo:

| Resource | Endpoint | Method | Data selector | Description | | --- | ---: | :---: | ---: | | | visits_summary | ?module=API&method=VisitsSummary.get&idSite={idSite}&period={period}&date={date}&format=JSON | GET | (top-level array) | Core metrics (visits, unique visitors, actions, bounce, etc.) | | actions_page_urls | ?module=API&method=Actions.getPageUrls&idSite={idSite}&period={period}&date={date}&format=JSON | GET | (top-level array) | Page URL report (pageviews, labels, ids) | | actions_downloads | ?module=API&method=Actions.getDownloads&idSite={idSite}&period={period}&date={date}&format=JSON | GET | (top-level array) | File downloads list (use &flat=1 to flatten) | | user_country | ?module=API&method=UserCountry.getCountry&idSite={idSite}&period={period}&date={date}&format=JSON | GET | (top-level array) | Visitor countries with metrics (label, nb_visits) | | api_bulk_request | ?module=API&method=API.getBulkRequest&format=JSON&urls[{i}]=... | GET/POST | (array/object as returned per subrequests) | Bulk multiple API calls in one request | | metadata_get_processed | ?module=API&method=API.getProcessedReport&idSite={idSite}&period={period}&date={date}&format=JSON&apiModule={Module}&apiAction={Action} | GET | data (if present) or top-level array | Returns processed, human-readable report (may include data key and metadata) | | wordpress_processed_report | /index.php?rest_route=/matomo/v1/api/processed_report&apiModule={Module}&apiActions={Action}&period={period}&date={date}&filter_limit={n} | GET | data | Matomo for WordPress wrapper endpoints; responses often include data key containing rows | | api_get_matomo_version | ?module=API&method=API.getMatomoVersion&format=JSON | GET | (top-level array or single value) | Returns Matomo instance version | | actions_get_pageurl | ?module=API&method=Actions.getPageUrl&pageUrl={url}&idSite={idSite}&period={period}&date={date}&format=JSON | GET | (top-level array) | Metrics for a specific page URL |

---

How do I authenticate with the Matomo API?

Provide token_auth in each request (as a query parameter for GET or in POST body for POST). Use HTTPS to protect the token. For Matomo for WordPress REST endpoints, authentication is handled by WordPress and token_auth is not required.

1. Get your credentials

1. Log into your Matomo web UI as the user for whom you want an API token. 2. Go to Administration → Personal → Security → Auth tokens (or "API" page in older versions). 3. Create a new auth token (or copy an existing one). Optionally restrict token to POST-only. 4. Keep token_auth secret and store it securely in your dlt secrets.

2. Add them to .dlt/secrets.toml

Copy
[sources.matomo_source]
api_key = "your_matomo_token_auth_here"

dlt reads this automatically at runtime — never hardcode tokens in your pipeline script. For production environments, see setting up credentials with dlt for environment variable and vault-based options.

---

How do I set up and run the pipeline?

Set up a virtual environment and install dlt:

Copy
uv venv && source .venv/bin/activate
uv pip install "dlt[workspace]"

1. Install the dlt AI Workbench:

Copy
dlt ai init --agent <your-agent> # <agent>: claude | cursor | codex

This installs project rules, a secrets management skill, appropriate ignore files, and configures the dlt MCP server for your agent. Learn more →

2. Install the rest-api-pipeline toolkit:

Copy
dlt ai toolkit rest-api-pipeline install

This loads the skills and context about dlt the agent uses to build the pipeline iteratively, efficiently, and safely. The agent uses MCP tools to inspect credentials — it never needs to read your secrets.toml directly. Learn more →

3. Start LLM-assisted coding:

Use /find-source to load data from the Matomo API into DuckDB.

The rest-api-pipeline toolkit takes over from here — it reads relevant API documentation, presents you with options for which endpoints to load, and follows a structured workflow to scaffold, debug, and validate the pipeline step by step.

4. Run the pipeline:

Copy
python matomo_pipeline.py

If everything is configured correctly, you'll see output like this:

Copy
Pipeline matomo_pipeline load step completed in 0.26 seconds
1 load package(s) were loaded to destination duckdb and into dataset matomo_data
The duckdb destination used duckdb:/matomo.duckdb location to store data
Load package 1749667187.541553 is LOADED and contains no failed jobs

Inspect your pipeline and data:

Copy
dlt pipeline matomo_pipeline show

This opens the Pipeline Dashboard where you can verify pipeline state, load metrics, schema (tables, columns, types), and query the loaded data directly.

---

Python pipeline example

This example loads visits_summary and actions_page_urls from the Matomo API into DuckDB. It mirrors the endpoint and data selector configuration from the table above:

Copy
import dlt
from dlt.sources.rest_api import RESTAPIConfig, rest_api_resources

@dlt.source
def matomo_source(token_auth=dlt.secrets.value):
    config: RESTAPIConfig = {
        "client": {
            "base_url": "https://{your-matomo-domain}/",
            "auth": {
                "type": "api_key",
                "api_key": token_auth,
            },
        },
        "resources": [
            {"name": "visits_summary", "endpoint": {"path": "?module=API&method=VisitsSummary.get"}},
            {"name": "actions_page_urls", "endpoint": {"path": "?module=API&method=Actions.getPageUrls"}}
        ],
    }
    yield from rest_api_resources(config)


def get_data() -> None:
    pipeline = dlt.pipeline(
        pipeline_name="matomo_pipeline",
        destination="duckdb",
        dataset_name="matomo_data",
    )
    load_info = pipeline.run(matomo_source())
    print(load_info)

To add more endpoints, append entries from the resource table to the "resources" list using the same name, path, and data_selector pattern.

---

How do I query the loaded data?

Once the pipeline runs, dlt creates one table per resource. You can query with Python or SQL.

Python (pandas DataFrame):

Copy
import dlt

data = dlt.pipeline("matomo_pipeline").dataset()
sessions_df = data.visits_summary.df()
print(sessions_df.head())

SQL (DuckDB example):

Copy
SELECT * FROM matomo_data.visits_summary LIMIT 10;

In a marimo or Jupyter notebook:

Copy
import dlt

data = dlt.pipeline("matomo_pipeline").dataset()
data.visits_summary.df().head()

See how to explore your data in marimo Notebooks and how to query your data in Python with dataset.

---

What destinations can I load Matomo data to?

dlt supports loading into any of these destinations — only the destination parameter changes:

Change the destination in dlt.pipeline(destination="snowflake") and add credentials in .dlt/secrets.toml. See the full destinations list.

---

Troubleshooting

Authentication failures

If you receive "Authentication failed" or empty/403 responses, ensure token_auth is correct, included as a query parameter for GET requests (or in POST body) and that you are using HTTPS. Verify the token in Matomo: Administration → Personal → Security → Auth tokens.

Pagination and filter_limit

By default many endpoints return top 100 rows. Use filter_limit=-1 to return all rows or set filter_limit={n}. Some responses include idsubdatatable; use idSubtable parameter to request subtables or use expanded=1 to fetch subtables inline (may increase payload).

Common API errors

• "The method 'X' does not exist or is not available in the module '\Piwik\Plugins\API\API'": the requested method name is incorrect; open the Matomo UI report and use the export icon to get the correct API method or consult the Reporting API reference.
• 401/403: missing/invalid token_auth or insufficient permissions.
• Empty responses: may indicate no data for date/idSite/segment combination.

Ensure that the API key is valid to avoid 401 Unauthorized errors. Also, verify endpoint paths and parameters to avoid 404 Not Found errors.

---

Next steps

Continue your data engineering journey with the other toolkits of the dltHub AI Workbench:

• data-exploration — Build custom notebooks, charts, and dashboards for deeper analysis with marimo notebooks.
• dlthub-runtime — Deploy, schedule, and monitor your pipeline in production.

Copy
dlt ai toolkit data-exploration install
dlt ai toolkit dlthub-runtime install

• How to deploy a pipeline
• How to explore your data in marimo Notebooks
• How to query your data in Python with dataset
• Join the dlt community on Slack