Matomo Core and Plugin Configuration files FAQ - On-Premise

Matomo uses configuration files to define system behaviour, manage environment-specific settings, and control how plugins and features operate.

The Matomo Core config file acts as the backbone of your Matomo setup by applying default settings consistently across your instance. Plugin configuration files are defined within each plugin’s codebase.

This guide explains where to find the core configuration and provides a consolidated reference of the default values for all Matomo plugins.

Settings for Matomo Core

The core configuration file for Matomo is config.ini.php. This file is created during installation and applies override values to the more extensive global.ini.php file.

The exact location of your config.ini.php depends on how you run Matomo:

Matomo Cloud: All server-side configuration is managed for you. If you need changes and the functionality is available on Cloud, you can contact Matomo support.
Matomo On-Premise: The configuration file is usually found in the /config/ folder in your Matomo installation (e.g., /var/www/html/matomo/config/config.ini.php on a typical Linux server). In container-based setups such as Docker, it may be located outside the application folder.
Matomo for WordPress: The configuration file is typically stored in the WordPress uploads folder at $WordPressRoot/wp-content/uploads/matomo/config/config.ini.php.

Note: The config.ini.php contains sensitive settings and should only be modified by the server administrator. It is important to set permissions on the file so that it cannot be changed or read by unauthorised users. Learn more about how to find and edit the Matomo configuration file.

Lists of Plugins

In addition to the Core configuration settings, the config.ini.php file also contains two lists of plugins. The section [PluginsInstalled] shows all plugins that are installed, while the section [Plugins] shows plugins that are both installed and activated.

Settings for Matomo Plugins

The following section may seem technical but it explains how plugin configuration settings are structured. It also includes examples to help you create effective configuration entries. If you still need assistance, contact Support for technical guidance.

The plugin config files include constants from the PHP code such as KEY_… or DEFAULT_…. These are shown for reference only and are not added as part of the configuration entry in the config.ini.php file. The parts you do want to focus on are shown after the constant’s equal (=) sign, which is usually an integer, a string, or a lower cased variable name (with underscores: referred to as snake_case).

In the underlying PHP code, configuration options are often defined in pairs: a KEY_ with a value naming the setting and a DEFAULT_ constant providing the default value. You will need to use both values (if applicable) in config.ini.php when overriding settings.

Remember: The goal is to write a single line of configuration which starts with a snake_case variable, followed by an equal (=) sign, and finally a value such as an integer or string.

Example 1: How to disable unique visitors in any plugin

This example describes how to disable the display of unique visitors by changing a configuration value. The reference in the plugin file is shown as:

KEY_SHOW_UNIQUE_VISITOR = show_unique_visitors
DEFAULT_SHOW_UNIQUE_VISITOR = 1

The config key is show_unique_visitors with a default set to 1 (enabled). To override the default and set to disabled, you would add the key and default values to the config.ini.php file:

[PluginName]
show_unique_visitors = 0

Example 2: How to reduce the number of dimensions in the Custom Reports plugin

This example describes how to block users from adding more than two dimensions in their Custom Reports. The reference in the Custom Reports plugin file is shown as:

KEY_MAX_DIMENSIONS = custom_reports_max_dimensions
DEFAULT_MAX_DIMENSIONS = 3

The config key is custom_reports_max_dimensions with a default set to 3. To override it and reduce the limit to 2, you would add the following line to the [CustomReports] section of your config.ini.php file:

[CustomReports]
custom_reports_max_dimensions = 2

After saving the file, no restart is required as Matomo checks the configuration every time it runs. Users will now be limited to two dimensions in Custom Reports, instead of the default 3.

The following sections list the configuration options for each Matomo-authored plugin.

[AbTesting]

The A/B Testing plugin lets you compare different versions of a page or feature to measure which performs better. Example config file:

Estimated Unique Visitor Enabled

Controls whether estimated unique visitors are calculated in A/B Testing reports. When enabled, Matomo uses statistical estimation methods to approximate unique visitor counts, which can improve performance on high-traffic sites. Default is disabled.

KEY_ESTIMATED_UNIQUE_VISITOR_ENABLED = enableEstimatedUniqueVisitors
DEFAULT_ESTIMATED_UNIQUE_VISITOR_ENABLED = 0

HyperLogLog Error Rate

Defines the acceptable error rate for HyperLogLog, the algorithm used to estimate unique visitors efficiently. Lower values increase accuracy but require more memory and processing. Higher values use fewer resources but provide less precision.

KEY_HYPERLOGLOG_ERROR_RATE = hyperLogErrorRate
DEFAULT_HYPERLOGLOG_ERROR_RATE = 0.01

Maximum HyperLogLog Bucket Archiving Rows

Sets the maximum number of HyperLogLog buckets (rows) stored during archiving. Larger values can improve accuracy for unique visitor estimates but also increase memory and storage requirements.

KEY_MAXIMUM_HYPERLOLOG_BUCKET_ARCHIVING_ROWS = datatable_archiving_maximum_hyperloglog_rows
DEFAULT_MAXIMUM_HYPERLOLOG_BUCKET_ARCHIVING_ROWS = 64000

Archive Unique Visitor Enabled

Determines whether true unique visitor counts are calculated and stored during archiving. Disabling this can reduce archiving time and resource usage, but unique visitor data will no longer be available in A/B Testing reports. Default is enabled.

KEY_ARCHIVE_UNIQUE_VISITOR_ENABLED = archive_unique_visitors_enabled
DEFAULT_ARCHIVE_UNIQUE_VISITOR_ENABLED = 1

Show Unique Visitor

Determines whether unique visitor counts are displayed in A/B Testing reports. Default is enabled.

KEY_SHOW_UNIQUE_VISITOR = show_unique_visitors
DEFAULT_SHOW_UNIQUE_VISITOR = 1

Show Estimated Unique Visitor

Determines whether estimated unique visitor counts are displayed in A/B Testing reports. Even if estimation is enabled and data is calculated, it will only be visible in the UI if this setting is turned on. Default is disabled.

KEY_SHOW_ESTIMATED_UNIQUE_VISITOR = show_estimated_unique_visitors
DEFAULT_SHOW_ESTIMATED_UNIQUE_VISITOR = 0

[AnonymousPiwikUsageMeasurement]

The Anonymous Matomo (Piwik) Usage Measurement plugin is designed to track anonymous usage statistics about the Matomo platform.

Tracking Domain

Defines the default Matomo server endpoint where anonymous usage data is sent. By default, this points to Matomo’s demo anonymous instance.

TRACKING_DOMAIN = https://demo-anonymous.matomo.org

Example Domain

Provides a placeholder website domain used in example tracking requests. It serves only as a sample value for demonstration and testing purposes.

EXAMPLE_DOMAIN = http://example.com

[AdvertisingConversionExport]

The Advertising Conversion Export plugin tracks and exports conversion data to ad platforms.

SALT

The salt setting is optional. If no salt is set, the plugin uses its built-in behaviour to handle click IDs and/or hashing. Read more on Exported clickIDs have value as anonymised.

KEY_SALT = salt

[Cohorts]

Analyse groups of users who share common characteristics or start dates, and compare their behaviour over time.

Periods from Start to Show

Controls how many time periods from the start of each cohort are displayed in reports. The default 10 shows ten periods (such as weeks or months) of cohort data.

KEY_PERIODS_FROM_START_TO_SHOW = periods_from_start_to_show
DEFAULT_PERIODS_FROM_START_TO_SHOW = 10

Num Cohorts to Show

Determines how many distinct cohorts are displayed in the Cohorts report at once. With the default 10, the table will list ten cohorts (such as users who started in ten different weeks).

KEY_NUM_COHORTS_TO_SHOW = num_cohorts_to_show
DEFAULT_NUM_COHORTS_TO_SHOW = 10

[CrashAnalytics]

Track, store, and analyse application crashes to identify stability issues and improve performance.

Delete Crash Data older than

Defines how long crash data is retained before being purged. This helps manage database size.

KEY_DELETE_CRASH_DATA_OLDER_THAN = delete_crash_data_older_than
DEFAULT_DELETE_CRASH_DATA_OLDER_THAN = 90

Datatable Archiving Maximum Rows Crashes

Sets the maximum number of rows stored in the main crash reports during archiving.

KEY_DATATABLE_ARCHIVING_MAXIMUM_ROWS_CRASHES = datatable_archiving_maximum_rows_crashes
DEFAULT_DATATABLE_ARCHIVING_MAXIMUM_ROWS_CRASHES = 500

Datatable Archiving Maximum Rows Crash Toptable

Sets the maximum number of rows shown in top-level crash tables (for example, top crash types).

KEY_DATATABLE_ARCHIVING_MAXIMUM_ROWS_CRASH_TOPTABLE = datatable_archiving_maximum_rows_crash_toptable
DEFAULT_DATATABLE_ARCHIVING_MAXIMUM_ROWS_CRASH_TOPTABLE = 500

Datatable Archiving Maximum Rows Crash Subtable

Sets the maximum number of rows displayed in crash subtables (for example, details within a specific crash type).

KEY_DATATABLE_ARCHIVING_MAXIMUM_ROWS_CRASH_SUBTABLE = datatable_archiving_maximum_rows_crash_subtable
DEFAULT_DATATABLE_ARCHIVING_MAXIMUM_ROWS_CRASH_SUBTABLE = 100

Consider Crash New after N Days

Determines how long a crash is considered new, which is useful for separating recent and long-standing issues.

KEY_CONSIDER_CRASH_NEW_AFTER_N_DAYS = consider_crash_new_after_n_days
DEFAULT_CONSIDER_CRASH_NEW_AFTER_N_DAYS = 365 * 2

Crash Ranking Query Limit

Defines the row limit used when ranking crashes during archiving. Affects performance and completeness of ranking queries.

KEY_CRASH_RANKING_QUERY_LIMIT = crash_archiving_ranking_query_row_limit
DEFAULT_CRASH_RANKING_QUERY_LIMIT = 50000

[CustomReports]

Create reports with specific dimensions and metrics for advanced reporting needs. Learn more on how to change the number of dimensions shown in a Custom Report.

Always Show Unique Visitor

Determines whether unique visitor counts are always displayed in custom reports. Default is disabled.

KEY_ALWAYS_SHOW_UNIQUE_VISITORS = custom_reports_always_show_unique_visitors
DEFAULT_ALWAYS_SHOW_UNIQUE_VISITORS = 0

Max Execution Time

Sets the maximum execution time allowed for generating a custom report. Default is no limit.

KEY_MAX_EXECUTION_TIME = custom_reports_max_execution_time
DEFAULT_MAX_EXECUTION_TIME = 0

Disabled Dimensions

Lists dimensions that are disabled for use in custom reports. Default is none disabled.

KEY_DISABLED_DIMENSIONS = custom_reports_disabled_dimensions
DEFAULT_DISABLED_DIMENSIONS = »

Evolution Unique Force Aggregation

Forces unique metrics to be aggregated when generating evolution reports for multiple periods. Default is disabled.

KEY_EVOLUTION_UNIQUE_FORCE_AGGREGATION = custom_reports_periods_force_aggregate_report_unique_metrics_evolution
DEFAULT_EVOLUTION_UNIQUE_FORCE_AGGREGATION = »

Validate Report Content All Websites

Determines whether report content is validated across all websites. Default is enabled.

KEY_VALIDATE_REPORT_CONTENT_ALL_WEBSITES = custom_reports_validate_report_content_all_websites
DEFAULT_VALIDATE_REPORT_CONTENT_ALL_WEBSITES = 1

Rearchive Reports in Past Last N Months

Controls how many months of past reports are re-archived when changes are made. You can override this behaviour by adding a value (number of months). For example, setting it to 6 would re-archive reports for the past six months.

KEY_REARCHIVE_REPORTS_IN_PAST_LAST_N_MONTHS = custom_reports_rearchive_reports_in_past_last_n_months

Max Dimensions

Sets the maximum number of dimensions that can be combined in a single custom report. Default is 3 dimensions.

KEY_MAX_DIMENSIONS = custom_reports_max_dimensions
DEFAULT_MAX_DIMENSIONS = 3

Archive Maximum Rows Custom Dimensions Default

Sets the maximum number of rows stored in custom report dimension tables. Default is 50 rows.

KEY_ARCHIVE_MAXIMUM_ROWS_CUSTOM_DIMENSIONS_DEFAULT = datatable_archiving_maximum_rows_custom_reports_dimensions_default
DEFAULT_ARCHIVE_MAXIMUM_ROWS_CUSTOM_DIMENSIONS_DEFAULT = 50

Archive Maximum Rows Sub Table Custom Dimensions Default

Sets the maximum number of rows stored in subtables for custom reports by default.

KEY_ARCHIVE_MAXIMUM_ROWS_SUB_TABLE_CUSTOM_DIMENSIONS_DEFAULT = datatable_archiving_maximum_rows_subtable_custom_reports_dimensions_default
DEFAULT_ARCHIVE_MAXIMUM_ROWS_SUB_TABLE_CUSTOM_DIMENSIONS_DEFAULT = 10

Archive Maximum Rows Custom Dimensions

Allows setting row limits per specific custom report dimension. The default is not explicitly defined (must be specified per dimension if needed).

KEY_ARCHIVE_MAXIMUM_ROWS_CUSTOM_DIMENSIONS = datatable_archiving_maximum_rows_custom_reports_dimensions_

Archive Maximum Rows Sub Table Custom Dimensions

Defines the maximum number of rows stored in sub tables for specific custom report dimensions. The key is extended per dimension so you can set row limits individually for each dimension’s subtable. The default is not explicitly defined (must be specified per dimension if needed).

KEY_ARCHIVE_MAXIMUM_ROWS_SUB_TABLE_CUSTOM_DIMENSIONS = datatable_archiving_maximum_rows_subtable_custom_reports_dimensions_

Preview Report Iterations

Lists the time frames used to generate preview reports. Multiple values can be provided, separated by commas. These determine how far back in time Matomo will check when producing preview data.

KEY_PREVIEW_REPORT_ITERATIONS = custom_reports_preview_report_timeframes
DEFAULT_PREVIEW_REPORT_ITERATIONS = -15 minutes,-1 hour,-3 hours,-6 hours

Preview Report Min Rows Required

Specifies the minimum number of rows required for a preview report to be generated. If fewer rows are found, the preview will not display. Default is 3 rows.

KEY_PREVIEW_REPORT_MIN_ROWS_REQUIRED = custom_reports_preview_report_min_rows_required
DEFAULT_PREVIEW_REPORT_MIN_ROWS_REQUIRED = 3

[CustomVariables]

Assign name-value pairs to visits or actions. These variables can capture additional business or user-specific information, and then be used for advanced segmentation, filtering, and reporting.

Num CustomVars Cache Key

By default, Matomo allows up to 5 custom variables per scope (visit or action). You can increase the internal cache key (e.g., CustomVariables.MaxNumCustomVariables = 8)used to determine the maximum number of custom variable slots available. Note this could impact the database size and performance since more columns are added to store the values.

MAX_NUM_CUSTOMVARS_CACHEKEY = CustomVariables.MaxNumCustomVariables

[DeviceDetectorCache]

Improve performance by caching device detection results when identifying browsers, devices, and operating systems.

Num Entries to Cache

Sets the maximum number of device detection results to cache. A larger cache reduces repeated lookups but uses more memory.

KEY_NUM_ENTRIES_TO_CACHE = num_cache_entries
DEFAULT_NUM_ENTRIES_TO_CACHE = 200000

Access Log Regex

Defines the regular expression used to parse entries in the web server access log. This must match the log format used by your server.

KEY_ACCESS_LOG_REGEX = access_log_regex
DEFAULT_ACCESS_LOG_REGEX = /^(\S+) (\S+) (\S+) (\S+) \[([^:]+):(\d+:\d+:\d+) ([^\]]+)\] \"(\S+) (.?) (\S+)\" (\S+) (\S+) "([^"])" "([^"]*)" (\d+)$/';

Access Log Regex Match Entry

Specifies which capture group from the access_log_regex contains the user agent string. If you change access_log_regex because your server logs are formatted differently, the group containing the user agent might move. In that case, you’d also need to adjust regex_match_entry to match the new group number.

KEY_ACCESS_LOG_REGEX_MATCH_ENTRY = regex_match_entry
DEFAULT_ACCESS_LOG_REGEX_MATCH_ENTRY = 14

Access Log Path

Sets the path to the server access log file that should be parsed for device detection. Adjust this if your server stores logs in a different location.

KEY_ACCESS_LOG_PATH = access_log_path
DEFAULT_ACCESS_LOG_PATH = /var/log/httpd/access_log

[FormAnalytics]

The Form Analytics configuration settings define limits for how many form requests, submissions, and fields are processed to balance functionality with performance.

Max No of Form Request Allowed

Sets the maximum number of form requests that can be tracked. This prevents overload from excessive or automated form activity.

KEY_MAX_NO_OF_FORM_REQUEST_ALLOWED = max_no_of_form_requests_allowed
DEFAULT_MAX_NO_OF_FORM_REQUEST_ALLOWED = 500

Max No of Form Submission Request Allowed

Sets the maximum number of form submissions that can be tracked. This ensures stability even on high-traffic sites with many submissions.

KEY_MAX_NO_OF_FORM_SUBMISSION_REQUEST_ALLOWED = max_no_of_form_submission_requests_allowed
DEFAULT_MAX_NO_OF_FORM_SUBMISSION_REQUEST_ALLOWED = 500

Max No of Form Fields Allowed

Defines the maximum number of form fields that can be tracked across all forms. This limit avoids excessive data collection and performance issues.

KEY_MAX_NO_OF_FORM_FIELDS_ALLOWED = max_no_of_form_fields_allowed
DEFAULT_MAX_NO_OF_FORM_FIELDS_ALLOWED = 2000

[Funnels]

The Funnels configuration settings control how many rows are stored in different funnel reports and how much data is processed at once.

Max Action Rows

Sets the maximum number of action rows (such as pageviews or events) stored in funnel reports.

KEY_MAX_ACTION_ROWS = funnels_num_max_rows_in_actions
DEFAULT_NUM_ENTRIES_IN_ACTIONS = 100

Max Referrers Rows

Sets the maximum number of referrer rows included in funnel reports. This limits how many referrer entries are processed when attributing traffic to funnels.

KEY_MAX_REFERRERS_ROWS = funnels_num_max_rows_in_referrers
DEFAULT_NUM_ENTRIES_IN_REFERRERS = 50

Max Populate at Once

Defines the maximum number of rows processed in one batch when populating funnel data. Higher values allow more data to be processed at once but may increase server load.

KEY_MAX_POPULATE_AT_ONCE = funnels_num_max_rows_populate_at_once
DEFAULT_NUM_ROWS_POPULATE_AT_ONCE = 60000

[HeatmapSessionRecording]

The Heatmap and Session Recording configuration settings define how tracking is optimised, how sessions are sampled, and how heatmaps are displayed.

Optimise Tracking Code

Optimises performance by adding the heatmap and session recording tracking code only when required. Default is enabled.

KEY_OPTIMIZE_TRACKING_CODE = add_tracking_code_only_when_needed
DEFAULT_OPTIMIZE_TRACKING_CODE = 1

Session Recording Sample Limits

Lists the available sampling options for session recordings and defines how many sessions can be recorded.

KEY_SESSION_RECORDING_SAMPLE_LIMITS = session_recording_sample_limits
DEFAULT_SESSION_RECORDING_SAMPLE_LIMITS = 50,100,250,500,1000,2000,5000

Enable Anonymous Session Recording Access

Controls whether anonymous users can access session recordings without authentication. Default is enabled.

KEY_ENABLE_ANONYMOUS_SESSION_RECORDING_ACCESS = session_recording_enable_anonymous_access
DEFAULT_ENABLE_ANONYMOUS_SESSION_RECORDING_ACCESS = »

Enable Load CSS from DB

Controls whether Matomo should load CSS stylesheets directly from the database instead of from the filesystem. Default is enabled.

KEY_ENABLE_LOAD_CSS_FROM_DB = load_css_from_db
DEFAULT_ENABLE_LOAD_CSS_FROM_DB = 1

Max Allowed Time on Page Column Limit

Configuration key for setting the default width to use when generating heatmaps. The default heatmap width in pixels (1920px) is used if no custom width is defined. The list of allowed screen widths (in pixels) reflect common device and monitor resolutions to ensure heatmaps render accurately.

MAX_ALLOWED_TIME_ON_PAGE_COLUMN_LIMIT = max_time_allowed_on_page_column_limit
KEY_DEFAULT_HEATMAP_WIDTH = default_heatmap_width
DEFAULT_HEATMAP_WIDTH = 1920
HEATMAP_ALLOWED_WIDTHS = [320, 360, 480, 600, 640, 900, 960, 1024, 1200, 1280, 1366, 1440, 1600, 1680, 1920, 2560]

[LoginLdap]

Enable authentication against an LDAP directory for centralised user management. The Login Ldap plugin allows users to log in with their LDAP credentials and can synchronise accounts and access rights into Matomo.

use_ldap_for_authentication = 1: By default, it is enabled (1) for Matomo to use LDAP for authentication instead of its internal user store only.
synchronize_users_after_login = 1: If enabled, user details (name, email, groups) are synchronised from LDAP each time the user logs in.
enable_synchronize_access_from_ldap = 0: If enabled, access levels (view, admin, superuser) are synchronised from LDAP attributes rather than being managed solely in Matomo. Default is disabled.
new_user_default_sites_view_access = '': Comma-separated list of site IDs that new LDAP users should have view access to by default. Empty = no automatic access.
user_email_suffix = '': Add the suffix to append to LDAP usernames to create email addresses (e.g. @example.com).
append_user_email_suffix_to_username = 1: By default, it is enabled (1) to append the user_email_suffix to the username when creating the Matomo account.
required_member_of = '': DN of an LDAP group the user must belong to in order to log in. Empty = no group restriction.
required_member_of_field = 'memberOf': LDAP attribute used to check group membership (default: memberOf).
ldap_user_filter = '': Additional LDAP filter applied when looking up users (e.g. (objectClass=person)).
ldap_user_id_field = 'uid': LDAP attribute that maps to the Matomo username (default: uid).
ldap_mail_field = 'mail': LDAP attribute used for the user’s email address.
ldap_password_field = 'userPassword': LDAP attribute used for password authentication.
ldap_view_access_field = 'view': LDAP attribute used to determine view access in Matomo.
ldap_admin_access_field = 'admin': LDAP attribute used to determine admin access in Matomo.
ldap_superuser_access_field = 'superuser': LDAP attribute used to determine superuser access in Matomo.
strip_domain_from_web_auth = 1: By default, it is enabled to strip the domain from usernames provided by web server authentication, e.g, user@example.com > user.
use_webserver_auth = 0: If enabled, Matomo trusts the web server’s authentication (e.g. HTTP auth) instead of prompting for a login form. Disabled by default.
user_access_attribute_server_specification_delimiter = ';': Delimiter used if multiple server specifications are stored in an LDAP attribute.
user_access_attribute_server_separator = ':': Separator between server name and access rights within a single LDAP attribute value.
instance_name = '': Identifier for the LDAP configuration instance (useful if running multiple instances).
ldap_network_timeout = Client::DEFAULT_TIMEOUT_SECS: Network timeout in seconds for LDAP connections (default defined by the client).
enable_password_confirmation = 0: If enabled, requires users to confirm their LDAP password for certain actions (e.g. linking accounts).
serverUrl = '': Provide the LDAP server connection URL (e.g. ldap://ldap.example.com:389).
baseDn = '': Provide the base Distinguished Name used as the search root for LDAP queries (e.g. dc=example,dc=com).

[MediaAnalytics]

Media Analytics default values define default behaviour and limits for how media analytics data is collected and archived in Matomo.

Maximum Rows in Datatable

Key for the maximum number of rows retained in top-level Media Analytics reports. By default, up to 1000 rows are kept when archiving main media reports.

MAXIMUM_ROWS_IN_DATATABLE = datatable_archiving_maximum_rows_media
DEFAULT_MAXIMUM_ROWS_IN_DATATABLE = 1000

Maximum Rows in Subtable

Key for the maximum number of rows retained in Media Analytics subtables (e.g. details under a media element). By default, up to 1000 rows are kept in subtables.

MAXIMUM_ROWS_IN_SUBTABLE = datatable_archiving_maximum_rows_subtable_media
DEFAULT_MAXIMUM_ROWS_IN_SUBTABLE = 1000

Enable Event Tracking

Key that controls whether event tracking is enabled automatically for media elements. Default is enabled.

ENABLE_EVENT_TRACKING = enable_event_tracking_by_default
DEFAULT_ENABLE_EVENT_TRACKING = 1

Archiving Ranking Query Row Limit Primary

Used to optimise performance when archiving large datasets by restricting how many rows are considered during ranking queries. Key and label for the primary ranking query row limit. By default, up to 10,000 rows are considered in primary ranking queries.

ARCHIVING_RANKING_QUERY_ROW_LIMIT_PRIMARY = archiving_ranking_query_row_limit_primary
RANKING_QUERY_TYPE_PRIMARY = primary
DEFAULT_RANKING_QUERY_LIMIT_PRIMARY = 10000

Archiving Ranking Query Row Limit Secondary

Key and label for the secondary ranking query row limit. By default, up to 75,000 rows are considered in secondary ranking queries.

ARCHIVING_RANKING_QUERY_ROW_LIMIT_SECONDARY = archiving_ranking_query_row_limit_secondary
RANKING_QUERY_TYPE_SECONDARY = secondary
DEFAULT_RANKING_QUERY_LIMIT_SECONDARY = 75000

[MultiChannelConversionAttribution]

Attribute conversions across multiple channels using different attribution models. These defaults control how many rows are retained in reports and whether reports can be invalidated when data changes.

Maximum Rows in Datatable

Key for the maximum number of rows retained in top-level attribution reports. By default, top-level attribution reports keep up to 500 rows when archived.

KEY_MAXIMUM_ROWS_IN_DATATABLE = datatable_archiving_maximum_rows
DEFAULT_MAXIMUM_ROWS_IN_DATATABLE = 500

Maximum Rows in Subtable

Key for the maximum number of rows retained in attribution subtables (for example, drill-down views). By default, subtables keep up to 500 rows.

KEY_MAXIMUM_ROWS_IN_SUBTABLE = datatable_archiving_maximum_rows_subtable
DEFAULT_MAXIMUM_ROWS_IN_SUBTABLE= 500

Available Days Prior Conversion

The list of lookback windows (in days) offered in the UI for attribution analysis. Users can select from 7, 30, 60, or 90 days before the conversion. The default lookback window, in days, used for attribution if none is selected.

KEY_AVAILABLE_DAYS_PRIOR_CONVERSION = available_days_prior_to_conversion
DEFAULT_AVAILABLE_DAYS_PRIOR_CONVERSION = 7,30,60,90

Day Prior Conversion

Config key for defining which lookback windows are available to choose from. Config key for defining the default number of days to use as the attribution window.

KEY_DAY_PRIOR_CONVERSION = default_day_prior_to_conversion
DEFAULT_DAY_PRIOR_CONVERSION = 30

Can Invalidate Reports General

Config key that determines whether reports can be invalidated and reprocessed when changes occur (for example, when attribution settings are updated).

KEY_CAN_INVALIDATE_REPORTS_GENERAL = can_invalidate_reports

[QueuedTracking]

Queue incoming tracking requests for background processing to improve performance under heavy load.

Notify Threshold

Default threshold for the number of queued tracking requests. When the number of requests in a queue exceeds this value, a notification can be triggered. It includes the config key for setting the threshold of queued requests per queue before sending a notification and the key for specifying the email addresses that should be notified.

KEY_NOTIFY_THRESHOLD = notify_queue_threshold_single_queue
DEFAULT_NOTIFY_THRESHOLD = 250000
KEY_NOTIFY_EMAILS = notify_queue_threshold_emails

Failed Tracking Requests

Config key that controls whether failed tracking request bodies are logged for troubleshooting. Default value is disabled (0). Failed tracking requests are not logged unless explicitly enabled.

LOG_FAILED_TRACKING_REQUESTS = log_failed_tracking_request_body
LOG_FAILED_TRACKING_REQUESTS_DEFAULT = 0

[RollUpReporting]

Aggregate data from multiple websites into unified roll-up reports. These settings control how raw data is processed and whether certain metrics (like unique visitors) are calculated for segments.

Force Aggregate Raw Data

Config key that forces Matomo to aggregate raw data when processing daily roll-up reports with segments applied and for all daily roll-up reports.

FORCE_AGGREGATE_RAW_DATA_FOR_DAY_SEGMENT = force_aggregate_raw_data_for_day_segment
DEFAULT_FORCE_AGGREGATE_RAW_DATA_FOR_DAY_SEGMENT = 1
FORCE_AGGREGATE_RAW_DATA_FOR_DAY = force_aggregate_raw_data_for_day
DEFAULT_FORCE_AGGREGATE_RAW_DATA_FOR_DAY = 1

Disable Processing Unique Visitors for Segment

Config key that controls whether unique visitors are calculated in roll-up reports when segments are applied. By default, unique visitor counts are processed for segmented roll-up reports.

DISABLE_PROCESSING_UNIQUE_VISITORS_FOR_SEGMENT = disable_processing_unique_visitors_for_segment
DEFAULT_DISABLE_PROCESSING_UNIQUE_VISITORS_FOR_SEGMENT = 0

[SEOWebVitals]

Report on key SEO Web Vitals metrics for your tracked websites. Config key that defines the maximum number of URLs per site that are monitored for Web Vitals metrics. Default value -1 means no limit and all URLs can be monitored unless restricted in configuration.

KEY_MAX_URLS_PER_SITE = max_urls_monitor_per_site
DEFAULT_MAX_URLS_PER_SITE = -1

[TagManager]

Control which Tag Manager components are enabled or disabled. Config key for disabling tags, triggers or variables in Matomo Tag Manager.

KEY_DISABLED_TAGS = disable_tags
KEY_DISABLED_TRIGGERS = disable_triggers
KEY_DISABLED_VARIABLES = disable_variables

[TrackingSpamPrevention]

Block unwanted traffic from bots and spam sources before it enters your analytics. These settings control IP range handling and organisation-based blocking.

Range Throw Exception

Config key that determines whether an exception should be thrown if an IP range sync fails. By default, no exception is thrown (0 = false). Errors are logged instead of interrupting processing.

KEY_RANGE_THROW_EXCEPTION = block_cloud_sync_throw_exception_on_error
DEFAULT_RANGE_THROW_EXCEPTION = 0

Range Allow List

Config key defining the list of IP ranges that are always allowed, bypassing spam prevention rules. By default, the allow list is empty.

KEY_RANGE_ALLOW_LIST = iprange_allowlist
DEFAULT_RANGE_ALLOW_LIST = ['']

GEOIP Match Providers

Config key for specifying which hosting providers or organisations (based on GeoIP lookup) should be blocked. Default blocklist of common cloud/hosting providers often associated with unwanted traffic.

KEY_GEOIP_MATCH_PROVIDERS = block_geoip_organisations
DEFAULT_GEOIP_MATCH_PROVIDERS = ['alicloud', 'alibaba cloud', 'digitalocean', 'digital ocean']

[UsersFlow]

Visualise how users move step-by-step through your website or app. These settings control report depth and limits to balance detail and performance.

Max Steps

Config key defining the maximum number of steps shown in a flow report. By default, flows are limited to 10 steps.

KEY_MAX_STEPS = UsersFlow_num_max_steps
DEFAULT_MAX_STEPS = 10

Max Actions per Table

Config key defining the maximum number of actions (rows) included per table in flow reports. By default, each actions table can include up to 100 rows.

KEY_MAX_ACTIONS_PER_TABLE = UsersFlow_num_max_rows_in_actions
DEFAULT_MAX_ACTIONS_PER_TABLE = 100

Max Links per Interaction

Config key defining the maximum number of links between actions that can be recorded for a single interaction. By default, up to 5000 links are allowed per interaction.

KEY_MAX_LINKS_PER_INTERACTION = UsersFlow_num_max_links_per_interaction
DEFAULT_MAX_LINKS_PER_INTERACTION = 5000

Level of Detail

Default level of detail for Users Flow visualisation. Higher values provide more granular paths. Default number of actions displayed per step in the flow.

DEFAULT_LEVEL_OF_DETAIL = 6
DEFAULT_NUM_ACTIONS_PER_STEP = 5

This page was last updated: September 2025

Next FAQ: Is there a Video that explains how to Install Matomo?

Previous FAQ: How to Set up Auto-Archiving of Your Reports