A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Matomo API is how an app or AI agent works with a Matomo analytics install: reading visit and page reports, pulling real-time and raw per-visit detail, managing goals, and adding or configuring tracked sites. Access is granted through a per-user token whose role on each site, from view through admin to Superuser, decides what every call can read or change, and an agent is limited to the sites and methods that user can reach. Matomo does not push events, so real-time figures come from polling rather than callbacks.
How an app or AI agent connects to Matomo determines what it can reach. The reporting and management methods run through one HTTP entry point, while visit tracking has its own, and each call carries an authentication token whose user permissions set the boundary.
The Reporting API answers at one entry point, index.php?module=API, with the report or management method named in the method parameter, such as VisitsSummary.get or SitesManager.addSite. It returns JSON, XML, CSV, or other formats chosen by the format parameter.
The Tracking API answers at a separate endpoint, matomo.php, and records pageviews and events into a site's logs. Most tracking needs no token, and a JSON body with a requests array sends many hits in one call.
Matomo's first-party MCP server lets an AI tool query analytics in plain language through the Model Context Protocol. It is included with Matomo Cloud and available for On-Premise through the McpServer plugin, and must be enabled by a Superuser. It mediates read requests to the Reporting API and returns structured data; all reasoning happens in the AI tool.
A token_auth is created per Matomo user and inherits that user's permissions on each site. It is sent with the request, and Matomo advises sending it in the POST body rather than the URL so it is not exposed in logs or shared links.
Where OAuth 2.0 is installed, an app can authenticate with a bearer token whose granted scopes set what it can reach, instead of using a token_auth.
The Matomo API is split into modules an agent names in the method parameter, such as VisitsSummary, Actions, Referrers, Live, Goals, Events, SitesManager, and UsersManager. Each module exposes its own methods, and some reach far more than visit reports, including site configuration and user access.
Read the headline visit metrics for a site and time range, such as visits, unique visitors, actions, and bounce rate.
Read page URL, page title, entry and exit page, download, outlink, and site-search reports.
Read where visits came from, including referrer type, search engines, keywords, social networks, and external websites.
Read real-time counters and raw, per-visit detail including IP, location, device, referrer, and every action in a visit.
Read goal conversion and event reports, and create, update, or delete the goals a site tracks.
Read site configuration, and add, update, or delete the websites tracked in Matomo.
Read the user list, and create, update, or delete users and set their per-site access level.
Record a pageview or an event into a site's analytics through the separate Tracking endpoint.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Visits & summaryRead the headline visit metrics for a site and time range, such as visits, unique visitors, actions, and bounce rate.3 | ||||||
| GET | /index.php?module=API&method=VisitsSummary.get | Get the core visit metrics for a site and period, including visits, unique visitors, actions, and bounce rate. | read | view | Current | |
Reading reports needs at least view access on the requested idSite. The method name is passed in the method query parameter to the single API entry point. Acts onreport Permission (capability) viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /index.php?module=API&method=VisitsSummary.getVisits | Get the number of visits for a site and period. | read | view | Current | |
Needs at least view access on the idSite. Acts onreport Permission (capability) viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /index.php?module=API&method=VisitTime.getByDayOfWeek | Get visit counts broken down by day of the week. | read | view | Current | |
Needs at least view access on the idSite. Acts onreport Permission (capability) viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Actions (pages & content)Read page URL, page title, entry and exit page, download, outlink, and site-search reports.4 | ||||||
| GET | /index.php?module=API&method=Actions.getPageUrls | Get the page URL report, with metrics per page visited. | read | view | Current | |
Needs at least view access on the idSite. The page report can be flattened or requested as a hierarchy. Acts onreport Permission (capability) viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /index.php?module=API&method=Actions.getPageTitles | Get the page title report, with metrics per page title. | read | view | Current | |
Needs at least view access on the idSite. Acts onreport Permission (capability) viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /index.php?module=API&method=Actions.getDownloads | Get the report of files downloaded from the site. | read | view | Current | |
Needs at least view access on the idSite. Acts onreport Permission (capability) viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /index.php?module=API&method=Actions.getSiteSearchKeywords | Get the keywords visitors typed into the site's internal search. | read | view | Current | |
Needs at least view access on the idSite, and site search must be configured for the site. Acts onreport Permission (capability) viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Referrers (acquisition)Read where visits came from, including referrer type, search engines, keywords, social networks, and external websites.3 | ||||||
| GET | /index.php?module=API&method=Referrers.getReferrerType | Get visits split by referrer type, such as direct entry, search engines, websites, social networks, and campaigns. | read | view | Current | |
Needs at least view access on the idSite. Acts onreport Permission (capability) viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /index.php?module=API&method=Referrers.getAll | Get a flattened report of all referrers, including search keywords, social networks, and external website URLs together. | read | view | Current | |
Needs at least view access on the idSite. This combines the separate referrer reports into one flat list. Acts onreport Permission (capability) viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /index.php?module=API&method=Referrers.getSearchEngines | Get the report of search engines that referred visits. | read | view | Current | |
Needs at least view access on the idSite. Acts onreport Permission (capability) viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Live (real-time visits)Read real-time counters and raw, per-visit detail including IP, location, device, referrer, and every action in a visit.3 | ||||||
| GET | /index.php?module=API&method=Live.getCounters | Get real-time counts of visits, actions, and visitors over the last lastMinutes minutes. | read | view | Current | |
Needs at least view access on the idSite. The lastMinutes parameter sets the real-time window. Real-time figures come from polling this method, as Matomo has no push. Acts onreport Permission (capability) viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /index.php?module=API&method=Live.getLastVisitsDetails | Get raw per-visit detail, including each visit's pages, events, IP address, location, device, referrer, and goal conversions. | read | view | Current | |
Returns individual visitor records rather than aggregates, including the visitor IP address and full location. Reading these needs at least view access on the idSite. Acts onvisit Permission (capability) viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /index.php?module=API&method=Live.getVisitorProfile | Get the full profile of a single visitor by visitorId, summarising every visit and action recorded for that person. | read | view | Current | |
The visitorId parameter selects the person. Returns individual visitor detail, so it needs at least view access on the idSite. Acts onvisit Permission (capability) viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Goals & eventsRead goal conversion and event reports, and create, update, or delete the goals a site tracks.4 | ||||||
| GET | /index.php?module=API&method=Events.getCategory | Get the event report grouped by event category. | read | view | Current | |
Needs at least view access on the idSite. Events.getAction and Events.getName give the same data grouped by action or name. Acts onreport Permission (capability) viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /index.php?module=API&method=Goals.get | Get goal conversion metrics for a site and period, such as conversions and conversion rate. | read | view | Current | |
Needs at least view access on the idSite. An idGoal parameter narrows to one goal. Acts onreport Permission (capability) viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /index.php?module=API&method=Goals.addGoal | Create a goal for a site, defining how a conversion is matched. | write | admin | Current | |
Managing goals needs admin access on the idSite. Parameters include name, matchAttribute, pattern, patternType, and revenue. Acts ongoal Permission (capability) adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /index.php?module=API&method=Goals.updateGoal | Update an existing goal's matching rules or settings. | write | admin | Current | |
Needs admin access on the idSite. The idGoal parameter selects the goal to change. Acts ongoal Permission (capability) adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Sites (SitesManager)Read site configuration, and add, update, or delete the websites tracked in Matomo.5 | ||||||
| GET | /index.php?module=API&method=SitesManager.getSiteFromId | Get the configuration of a single site, such as its name, main URL, time zone, and currency. | read | view | Current | |
Reading site configuration needs at least view access on the idSite. Acts onsite Permission (capability) viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /index.php?module=API&method=SitesManager.getAllSites | Get the configuration of every site in the Matomo install. | read | superuser | Current | |
Listing every site needs Superuser access. SitesManager.getSitesWithAtLeastViewAccess returns only the sites the token's user can reach. Acts onsite Permission (capability) superuserVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /index.php?module=API&method=SitesManager.addSite | Create a new tracked website, with its name, URLs, time zone, currency, and other settings. | write | superuser | Current | |
Adding a site needs Superuser access. The urls parameter accepts an array of URLs for the site. Acts onsite Permission (capability) superuserVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /index.php?module=API&method=SitesManager.updateSite | Update an existing site's configuration. | write | admin | Current | |
Updating a site needs admin access on the idSite. Acts onsite Permission (capability) adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /index.php?module=API&method=SitesManager.deleteSite | Delete a website from Matomo by its ID. | write | superuser | Current | |
Deleting a site needs Superuser access. This removes the site configuration; existing logs and archives are handled separately. Acts onsite Permission (capability) superuserVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Users (UsersManager)Read the user list, and create, update, or delete users and set their per-site access level.4 | ||||||
| GET | /index.php?module=API&method=UsersManager.getUsers | Get the list of Matomo users. | read | admin | Current | |
Reading the user list needs admin access, since it returns who can sign in to Matomo. Acts onuser Permission (capability) adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /index.php?module=API&method=UsersManager.addUser | Create a new Matomo user. | write | superuser | Current | |
Creating a user needs Superuser access. Acts onuser Permission (capability) superuserVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /index.php?module=API&method=UsersManager.setUserAccess | Set a user's access level on one or more sites, from no access through view, write, and admin. | write | superuser | Current | |
Granting access needs Superuser access. The access parameter takes noaccess, view, write, or admin. This is the method that controls what every other token can reach. Acts onuser Permission (capability) superuserVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /index.php?module=API&method=UsersManager.deleteUser | Delete a Matomo user. | write | superuser | Current | |
Deleting a user needs Superuser access. Acts onuser Permission (capability) superuserVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TrackingRecord a pageview or an event into a site's analytics through the separate Tracking endpoint.1 | ||||||
| POST | /matomo.php | Record a pageview or an event into a site's logs through the separate Tracking endpoint, using parameters such as idsite, rec, action_name, url, and the event fields e_c, e_a, e_n. | write | — | Current | |
Basic tracking needs no token. A token_auth is required only for privileged tracking, such as overriding the visitor IP, location, or timestamp, or sending data older than 24 hours. A POST body with a requests array sends many events at once. Acts onvisit Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Matomo does not push events to a receiver. An app or AI agent gets data by calling a reporting method, and real-time figures come from polling the Live module rather than from a callback.
| Event | What it signals | Triggered by |
|---|
Matomo sets no fixed request quota on a self-hosted install, where throughput is bounded by the server. Result size is controlled per call through the filter_limit and filter_offset parameters rather than a global page size.
Matomo sets no fixed request quota on a self-hosted install. How fast an app or AI agent can call is bounded by the server it runs on, and heavy methods such as Live.getCounters on a large database can be slow because of the work they do. Matomo Cloud applies its own limits to protect shared infrastructure. Result size per call is controlled by filter_limit, so a smaller limit returns faster.
Reporting methods page through results with filter_limit, which sets how many rows to return and defaults to 100, and filter_offset, which sets the starting row. Setting filter_limit to -1 returns every row, which should be used with care on large reports.
There is no single documented payload size limit. The format parameter selects JSON, XML, CSV, TSV, HTML, or the original data structure, and filter_limit bounds how many rows a report returns. Live.getLastVisitsDetails can return large per-visit payloads, so a date range and filter_limit keep responses manageable.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 200 | result=error | Matomo signals API errors inside a normal HTTP 200 response. The body carries result set to error and a message field describing what went wrong, such as a missing parameter or an access denial. | Parse the body and check the result field rather than relying on the HTTP status, then read the message to see what to fix. |
| 400 | Bad Request | From Matomo 5.7.1, an invalid idSite that was previously ignored can return 400. From Matomo 5.8.0, conflicting token_auth or force_api_session values across request sources also fail with 400. | Send a valid integer idSite and a single, consistent authentication value per request. |
| 401 | Access denied | The token is missing, invalid, or its user lacks the permission the method needs, such as admin for managing goals or Superuser for managing sites and users. | Send a valid token whose user has the required access level on the requested site. |
Matomo ships dated platform releases rather than versioning the HTTP API by URL. The current line is Matomo 5, and the method names and parameters stay stable across point releases, with changes announced in the platform changelog.
Matomo 5 is the current major line. The HTTP API is not versioned by URL, so method names and parameters stay stable across point releases, and notable changes ship through the platform changelog. Recent point releases tightened API input handling and added the first-party MCP server.
Matomo 5.0.0 opened the current major line, released in December 2023. It kept the same single-entry-point HTTP API model, with methods named in the method parameter, so existing integrations continued to call the same method names.
An integration calls the same method names across Matomo 5 point releases; breaking changes are flagged in the changelog.
Matomo platform changelog ↗Bollard AI sits between a team's AI agents and Matomo. Grant each agent exactly the access it needs, read or write, report by report, and every call is checked and logged.