Required parameters

Your Matomo host


The ID of the website we're tracking a visit/action for


Required for tracking, must be set to 1


(We recommend that these parameters be used if the information is available and relevant to your use case.)


The full HTTP Referrer URL. This value is used to determine how someone got to your website (ie, through a website, search engine or campaign)


The resolution of the device the visitor is using, eg 1280x1024.


The current hour (local time).


The current minute (local time).


The current second (local time).


When set to 1, the visitor's client is known to support cookies.


An override value for the User-Agent HTTP header field. The user agent is used to detect the operating system and browser used.


JSON encoded Client Hints collected by javascript. This will be used to enrich the detected user agent data. (requires Matomo 4.12.0)


An override value for the Accept-Language HTTP header field. This value is used to detect the visitor's country if GeoIP is not enabled.


Defines the User ID for this request. User ID is any non-empty unique string identifying the user (such as an email address or a username). To access this value, users must be logged-in in your system so you can fetch this user ID from your system, and pass it to Matomo. The User ID appears in the visits log, the Visitor profile, and you can Segment reports for one or several User ID (userId segment). When specified, the User ID will be "enforced". This means that if there is no recent visit with this User ID, a new one will be created. If a visit is found in the last 30 minutes with your specified User ID, then the new action will be recorded to this existing visit.


defines the visitor ID for this request. You must set this value to exactly a 16 character hexadecimal string (containing only characters 01234567890abcdefABCDEF). We recommended setting the User ID via uid rather than use this cid.


If set to 1, will force a new visit to be created for this action. This feature is also available in JavaScript.


An external URL the user has opened. Used for tracking outlink clicks. We recommend to also set the url parameter to this same value.


URL of a file the user has downloaded. Used for tracking downloads. We recommend to also set the url parameter to this same value.


The Site Search keyword. When specified, the request will not be tracked as a normal pageview but will instead be tracked as a Site Search request.


when search is specified, you can optionally specify a search category with this parameter.


when search is specified, we also recommend setting the search_count to the number of search results displayed on the results page. When keywords are tracked with &search_count=0 they will appear in the "No Result Search Keyword" report.


Accepts a six character unique ID that identifies which actions were performed on a specific page view. When a page was viewed, all following tracking requests (such as events) during that page view should use the same pageview ID. Once another page was viewed a new unique ID should be generated. Use [0-9a-Z] as possible characters for the unique ID.


If specified, the tracking request will trigger a conversion for the goal of the website being tracked with this ID.


A monetary value that was generated as revenue by this goal conversion. Only used if idgoal is specified in the request.


The amount of time it took the server to generate this action, in milliseconds. This value is used to process the Page speed report Avg. generation time column in the Page URL and Page Title reports, as well as a site wide running average of the speed of your server. Note: when using the JavaScript tracker this value is set to the time for server to generate response + the time for client to download response.


The charset of the page being tracked. Specify the charset if the data you send to Matomo is encoded in a different character set than the default utf-8.


Stands for custom action. &ca=1 can be optionally sent along any tracking request that isn't a page view. For example it can be sent together with an event tracking request e_a=Action&e_c=Category&ca=1. The advantage being that should you ever disable the event plugin, then the event tracking requests will be ignored vs if the parameter is not set, a page view would be tracked even though it isn't a page view. For more background information check out #16570. Do not use this parameter together with a ping=1 tracking request.

Custom Variables

Visit scope custom variables. This is a JSON encoded string of the custom variable array (see below for an example value). (Note: it is recommended to use "Custom Dimensions" instead of "Custom Variables")


This is a JSON encoded string of the custom variable array (see below for an example value).

Custom Dimensions

A Custom Dimension value for a specific Custom Dimension ID (requires Matomo 2.15.1 + Custom Dimensions plugin). If Custom Dimension ID is 2 use dimension2=dimensionValue to send a value for this dimension.


Must not be empty. (eg. Videos, Music, Games...)


Must not be empty. (eg. Play, Pause, Duration, Add Playlist, Downloaded, Clicked...)


(eg. a Movie name, or Song name, or File name...)


Must be a float or integer value (numeric), not a string.

Note: Trailing and leading whitespaces will be trimmed from parameter values for e_c, e_a and e_n. Strings filled with whitespaces will be considered as (invalid) empty values.










Acquisition Channel Attribution

In Matomo, it is possible to measure the channel used by the visitor to find the website, and then to attribute conversions to specific campaigns or channels. This is useful to identify which marketing efforts are driving the most traffic and conversions.


The Campaign name used to attribute goal conversions. (Note: this will only be used to attribute goal conversions, not visits)


The Campaign keyword used to attribute goal conversions. (Note: this will only be used to attribute goal conversions, not visits)

Page Performance

How long it took to connect to server.


How long it took the server to generate page.


How long it takes the browser to download the response from the server.


How long the browser spends loading the webpage after the response was fully received until the user can start interacting with it.


How long it takes for the browser to load media and execute any Javascript code listening for the DOMContentLoaded event.


How long it takes the browser to execute Javascript code waiting for the window.load event.

Content Tracking

To track a content impression set c_n and optionally c_p and c_t. To track a content interaction set c_i and c_n and optionally c_p and c_t. To map an interaction to an impression make sure to set the same value for c_n and c_p. It is recommended to set a value for c_p.


For instance 'Ad Foo Bar'.


For instance the path to an image, video, audio, any text.


For instance the URL of a landing page.


For instance a 'click'.


Use the following values to record a cart and/or an ecommerce order. You must set &idgoal=0 in the request to track an ecommerce interaction: cart update or an ecommerce order.


Unique string identifier for the ecommerce order (required when tracking an ecommerce order)


Items in the Ecommerce order. This is a JSON encoded array of items.


(required when tracking an ecommerce order)


Excludes shipping.




Media Analytics

Analytics for your Media content (video players and audio players) can be recorded using the premium Media Analytics plugin's HTTP Tracking API parameters.


A unique id that is always the same while playing a media. As soon as the played media changes (new video or audio started), this ID has to change.


The media title


The URL of the media resource.


Video or audio depending on the type of the media.


The name of the media player, for example html5.


The time in seconds for how long a user has been playing this media. This number should typically increase when you send a media tracking request. It should be 0 if the media was only visible/impressed but not played. Do not increase this number when a media is paused.


The duration (the length) of the media in seconds. For example if a video is 90 seconds long, the value should be 90.


The progress / current position within the media. Defines basically at which position within the total length the user is currently playing.


Defines after how many seconds the user has started playing this media. For example a user might have seen the poster of the video for 30 seconds before a user actually pressed the play button.


The resolution width of the media in pixels. Only recommended being set for videos.


The resolution height of the media in pixels. Only recommended being set for videos.


Should be 0 or 1 and defines whether the media is currently viewed in full screen. Only recommended being set for videos.


An optional comma separated list of which positions within a media a user has played. For example if the user has viewed position 5s, 10s, 15s and 35s, then you would need to send 5,10,15,35. We recommend to round to the next 5 seconds and not send a value for each second. Internally, Matomo may round to the next 15 or 30 seconds. For performance optimisation we recommend not sending the same position twice. Meaning if you have sent ma_se=10 there is no need to send later ma_se=10,20 but instead only ma_se=20.

Queued Tracking

Queued Tracking can scale your large traffic Matomo (Piwik) service by queuing tracking requests in Redis or Mysql for better performance and reliability when you experience peaks.


When set to 0 (zero), the queued tracking handler won't be used and instead the tracking request will be executed directly. This can be useful when you need to debug a tracking problem or want to test that the tracking works in general.

Other Parameters

32 character authorization key used to authenticate the API request. We recommend creating a user specifically for accessing the Tracking API, and give the user only write permission on the website(s).


Override value for the visitor IP (both IPv4 and IPv6 notations supported).


Override for the datetime of the request (normally the current time is used). This can be used to record visits and page views in the past. The expected format is either a datetime such as: 2011-04-05 00:11:42 (remember to URL encode the value!), or a valid UNIX timestamp such as 1301919102. The datetime must be sent in UTC timezone. Note: if you record data in the past, you will need to force Matomo to re-process reports for the past dates. If you set cdt to a datetime older than 24 hours then token_auth must be set. If you set cdt with a datetime in the last 24 hours then you don't need to pass token_auth.


An override value for the country. Should be set to the two letter country code of the visitor (lowercase), eg fr, de, us.


An override value for the region. Should be set to a ISO 3166-2 region code, which are used by MaxMind's and DB-IP's GeoIP2 databases.


An override value for the city. The name of the city the visitor is located in, eg, Tokyo.


An override value for the visitor's latitude, eg 22.456.


An override value for the visitor's longitude, eg 22.456.


If set to 0 (send_image=0) Matomo will respond with an HTTP 204 response code instead of a GIF image. This improves performance and can fix errors if images are not allowed to be obtained directly (eg Chrome Apps). Available since Matomo 2.10.0.


If set to 1 (ping=1), the request will be a Heartbeat request which will not track any new activity (such as a new visit, new action or new goal). The heartbeat request will only update the visit's total time to provide accurate "Visit duration" metric when this parameter is set. It won't record any other data. This means by sending an additional tracking request when the user leaves your site or app with &ping=1, you fix the issue where the time spent of the last page visited is reported as 0 seconds.

Tracking Bots

By default Matomo does not track bots. If you use the Tracking HTTP API directly, you may be interested in tracking bot requests. To enable Bot Tracking in Matomo, set the parameter &bots=1 in your requests to matomo.php.

Copy this URL