How to use AI with the Matomo API

Cloud Auto-hébergement

AI assistants such as ChatGPT, Claude, Copilot, and Gemini can help you understand, build, and troubleshoot requests to the Matomo API. For example, use AI to explain an API method, suggest a practical use case, or generate a request.

If you have integrated the Matomo MCP Server with AI tools, you can allow the AI assistant to interact directly with your Matomo instance. See integrating the MCP Server.

This guide provides practical examples to help you get started with using AI and the Matomo API.

Before you start

  • Keep your authentication token secure. Treat your Matomo authentication token like a password and do not paste it into a public AI tool, shared conversation, or prompt that could be stored or reviewed. It is recommended to insert a placeholder while generating a request, then replace it with the real token only in a secure environment.
  • Review AI-generated requests before running them. AI-generated responses can be inaccurate or contain actions that modify your Matomo configuration.
  • Always verify the request against the Matomo API reference before executing it.

Example AI prompts

The Matomo API reference makes it easier to find available methods, review their parameters, and test requests. AI can complement this reference by explaining methods in plain language and helping you adapt requests for a specific use case.

1. Understand an API method

If you are unfamiliar with an API method, copy the method from the Matomo API reference and ask an AI tool to explain what it does and when you would use it.

AI can explain the purpose of the method, describe the returned data, identify the required parameters, and suggest common use cases. This can help with understanding unfamiliar API methods before you build or execute a request.

Example prompt

  • Explain the Goals.getGoals API method. What does it return, when would I use it, and can you provide a practical example?

Example AI response

Goals.getGoals returns the goals configured for a specific website. You can use it to retrieve goal names, IDs, matching conditions, and other configuration details before updating or auditing goals. For example, a script could call this method before creating a new goal to check whether an equivalent goal already exists.

2. Generate API requests

Use AI to generate complete API requests from a natural language description with the required parameters (and include optional parameters if needed).

Example prompts

  • Generate a Goals.addGoal API request to create a goal that tracks contact form submissions.
  • Generate a SitesManager.getAllSites API request to retrieve all websites.
  • Generate a UsersManager.getUsers API request to list all users.
  • Generate a VisitsSummary.get API request to return the last 30 days of visit data for website ID 62.

AI can identify the appropriate API method, include the required parameters, and generate example requests in your preferred language or format, such as cURL, PHP, Python, or JavaScript.

3. Explain required parameters

Use AI to understand which parameters are required and how they affect an API request.

Example prompt

  • Explain the required and optional parameters for the Goals.addGoal API method. What does each parameter do, and when should I use it?

AI can explain the purpose of each parameter, such as:

  • idSite identifies the website where the goal will be created.
  • name specifies the goal name displayed in Matomo.
  • matchAttribute specifies the visitor attribute to evaluate, such as the URL or page title.
  • pattern specifies the value to match.
  • patternType defines how the pattern should be matched, such as exact or contains.

This helps to understand how each parameter affects the request before you execute it.

4. Create code snippets

AI can generate complete code examples in your preferred language, helping you integrate the Matomo API into websites, applications, or automation workflows.

Example prompts

  • Generate a JavaScript example that retrieves today’s visits using the VisitsSummary.get API method.
  • Generate a Python script that authenticates with the Matomo API and retrieves all websites.
  • Generate a cURL request to create a goal using the Goals.addGoal API method.
  • Convert this cURL request into PHP using the Matomo HTTP API.

4. Work with Analytics and Tracking APIs

Use AI to identify the appropriate API method for retrieving analytics data, sending tracking requests, or understanding the differences between the Reporting API and the Tracking API.

Example prompts

  • Which Reporting API method returns the top landing pages for the last 30 days?
  • Generate a request to retrieve page URLs with the highest number of page views.
  • Generate a Tracking API request that records a page view with a custom dimension.
  • Explain the difference between the Reporting API and the Tracking API.

5. Turn API data into reports and charts

Use AI to transform API responses into summaries, reports, dashboards, or visualisations.

Example prompts

  • Summarise this Matomo API response into an executive report.
  • Create a monthly traffic report from this JSON response.
  • Generate a bar chart showing the top 10 pages by page views.
  • Compare the last 30 days with the previous 30 days and highlight the biggest changes.
  • Identify unusual traffic patterns from this API response.

6. Automate Matomo administration

Use AI to generate API requests, scripts, or automation workflows that perform repetitive administration tasks instead of completing them manually.

Example prompts

  • Generate a Python script that uses the Matomo API to create the same goal across multiple websites.
  • Generate a script that updates the time zone for all websites.
  • Create a script that exports all configured goals for every website.
  • Generate a script that audits website settings and reports any missing site search configuration.

Always verify AI-generated requests and scripts against the Matomo API reference before executing them.

Next steps

Explore the Matomo API reference to discover available API methods and test requests. Start with a simple read-only API request to become familiar with the request format and response.

If you have integrated the Matomo MCP Server with AI tools, you can allow the AI assistant to interact directly with your Matomo instance. See integrating the MCP Server.

Previous FAQ: How do I find the website ID, also called idSite or Site ID?