# Matomo Events API

**Canonical:** https://apis.io/apis/matomo/matomo-events-api/  
**Provider:** Matomo — https://apis.io/providers/matomo/  
**Base URL:** https://{matomo_host}/index.php  
**Documentation:** https://developer.matomo.org/api-reference/reporting-api

Matomo Events API is one of 61 APIs that [Matomo](https://apis.io/providers/matomo/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. Tagged areas include Event. The published artifact set on APIs.io includes an OpenAPI specification and API documentation.

The Events API lets you request reports about your users' Custom Events. Events are tracked using the Javascript Tracker trackEvent() function, or using the [Tracking HTTP API](https://developer.matomo.org/api-reference/tracking-api). <br/>An event is defined by an event category (Videos, Music, Games...), an event action (Play, Pause, Duration, Add Playlist, Downloaded, Clicked...), and an optional event name (a movie name, a song title, etc.) and an optional numeric value. <br/>This API exposes the following Custom Events reports: <code>getCategory</code> lists the top Event Categories, <code>getAction</code> lists the top Event Actions, <code>getName</code> lists the top Event Names. <br/>These Events report define the following metrics: nb_uniq_visitors, nb_visits, nb_events. If you define values for your events, you can expect to see the following metrics: nb_events_with_value, sum_event_value, min_event_value, max_event_value, avg_event_value <br/>The Events.get* reports can be used with an optional <code>&secondaryDimension</code> parameter. Secondary dimension is the dimension used in the sub-table of the Event report you are requesting. <br/>Here are the possible values of <code>secondaryDimension</code>: <ul> <li>For <code>Events.getCategory</code> you can set <code>secondaryDimension</code> to <code>eventAction</code> or <code>eventName</code>.</li> <li>For <code>Events.getAction</code> you can set <code>secondaryDimension</code> to <code>eventName</code> or <code>eventCategory</code>.</li> <li>For <code>Events.getName</code> you can set <code>secondaryDimension</code> to <code>eventAction</code> or <code>eventCategory</code>.</li> </ul> <br/>For example, to request all Custom Events Categories, and for each, the top Event actions, you would request: <code>method=Events.getCategory&secondaryDimension=eventAction&flat=1</code>. You may also omit <code>&flat=1</code> in which case, to get top Event actions for one Event category, use <code>method=Events.getActionFromCategoryId</code> passing it the <code>&idSubtable=</code> of this Event category.

## Operations (9)

| Method | Path | Summary |
|---|---|---|
| GET | `/index.php?module=API&method=Events.getCategory` | — |
| GET | `/index.php?module=API&method=Events.getAction` | — |
| GET | `/index.php?module=API&method=Events.getName` | — |
| GET | `/index.php?module=API&method=Events.getActionFromCategoryId` | — |
| GET | `/index.php?module=API&method=Events.getNameFromCategoryId` | — |
| GET | `/index.php?module=API&method=Events.getCategoryFromActionId` | — |
| GET | `/index.php?module=API&method=Events.getNameFromActionId` | — |
| GET | `/index.php?module=API&method=Events.getActionFromNameId` | — |
| GET | `/index.php?module=API&method=Events.getCategoryFromNameId` | — |

## Machine-readable artifacts (5)

- **OpenAPI** — https://raw.githubusercontent.com/api-evangelist/matomo/refs/heads/main/openapi/matomo-events-api-openapi.yml
- **Documentation** — https://developer.matomo.org/api-reference/reporting-api
- **Documentation** — https://developer.matomo.org/api-reference/reporting-api#Live
- **Documentation** — https://developer.matomo.org/api-reference/reporting-api#Goals
- **Documentation** — https://developer.matomo.org/api-reference/reporting-api-segmentation

## Other Matomo APIs (12)

- [Matomo Reporting API (index.php entrypoint)](https://apis.io/apis/matomo/matomo-index-php-api/)
- [Matomo Tracking API (matomo.php entrypoint)](https://apis.io/apis/matomo/matomo-matomo-php-api/)
- [Matomo Ab Testing API](https://apis.io/apis/matomo/matomo-abtesting-api/)
- [Matomo Actions API](https://apis.io/apis/matomo/matomo-actions-api/)
- [Matomo Activity Log API](https://apis.io/apis/matomo/matomo-activitylog-api/)
- [Matomo Advertising Conversion Export API](https://apis.io/apis/matomo/matomo-advertisingconversionexport-api/)
- [Matomo Annotations API](https://apis.io/apis/matomo/matomo-annotations-api/)
- [Matomo API](https://apis.io/apis/matomo/matomo-api-api/)
- [Matomo API Reference API](https://apis.io/apis/matomo/matomo-apireference-api/)
- [Matomo Bandwidth API](https://apis.io/apis/matomo/matomo-bandwidth-api/)
- [Matomo Cohorts API](https://apis.io/apis/matomo/matomo-cohorts-api/)
- [Matomo Contents API](https://apis.io/apis/matomo/matomo-contents-api/)

## Tags

Event

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/matomo/matomo-events-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/matomo/.