Parameters Reference

Complete reference for all API parameters.

Standard Parameters

These parameters are required or commonly used in most API requests.

idSite

The website ID to query.

Value	Description
`1`	Single website
`1,2,3`	Multiple websites
`all`	All websites (limited support)


&idSite=1

period

The time period for the report.

Value	Description
`day`	Daily data
`week`	Weekly data (week containing the date)
`month`	Monthly data
`year`	Yearly data
`range`	Custom date range


&period=day

date

The date or date range for the report.

Single dates:

Value	Description
`today`	Current day
`yesterday`	Previous day
`YYYY-MM-DD`	Specific date

Relative ranges:

Value	Description
`lastX`	Last X periods including today
`previousX`	X periods before today
`lastWeek`	Previous calendar week
`lastMonth`	Previous calendar month
`lastYear`	Previous calendar year

Date ranges (with period=range):


&period=range&date=2024-01-01,2024-01-31

format

The output format.

Value	Description
`JSON`	JSON format (recommended)
`xml`	XML format
`csv`	Comma-separated values
`tsv`	Tab-separated values
`html`	HTML table
`rss`	RSS feed
`original`	PHP serialized (for internal use)


&format=JSON

token_auth

Authentication token.


&token_auth=YOUR_TOKEN_HERE

See Authentication for details.

Optional Parameters

Pagination & Limiting

filter_limit

Number of rows to return.

Value	Description
`10`	Return 10 rows
`100`	Return 100 rows (default)
`-1`	Return all rows


&filter_limit=25

filter_offset

Number of rows to skip (for pagination).


&filter_offset=20&filter_limit=10

filter_truncate

Truncate results and aggregate remaining rows into “Others”.


&filter_truncate=10

Sorting

filter_sort_column

Column to sort by.


&filter_sort_column=nb_visits

filter_sort_order

Sort direction.

Value	Description
`desc`	Descending (highest first)
`asc`	Ascending (lowest first)


&filter_sort_order=desc

Column Selection

showColumns

Only include specified columns (comma-separated).


&showColumns=nb_visits,nb_actions,bounce_rate

hideColumns

Exclude specified columns (comma-separated).


&hideColumns=logo,segment

Filtering

filter_pattern

Regular expression to match row labels.


&filter_pattern=google

filter_column

Column to apply filter_pattern to (default: label).


&filter_column=label&filter_pattern=blog

filter_excludelowpop

Column to use for minimum value threshold.


&filter_excludelowpop=nb_visits&filter_excludelowpop_value=10

filter_excludelowpop_value

Minimum value for the filter_excludelowpop column.

Hierarchical Data

expanded

Include subtables in the response.

Value	Description
`0`	Only top level (default)
`1`	Include all subtables


&expanded=1

flat

Flatten hierarchical data into single table.


&flat=1

idSubtable

Request a specific subtable by ID.


&idSubtable=123

Formatting

language

Language for translated strings (2-letter code).


&language=en

translateColumnNames

Translate column names to specified language.

Value	Description
`0`	Use technical names
`1`	Use translated names


&translateColumnNames=1

format_metrics

Control metric formatting.

Value	Description
`0`	Raw values (no formatting)
`1`	Formatted values (with %, currency, etc.)


&format_metrics=1

Segments

segment

Filter data by segment conditions.


&segment=browserCode==FF;countryCode==US

See Segmentation for complete documentation.

Advanced

showMetadata

Include metadata in response (available since Matomo 5.4).

Value	Description
`1`	Include metadata (default)
`0`	Exclude metadata


&showMetadata=0

disable_generic_filters

Disable all generic filters.


&disable_generic_filters=1

disable_queued_filters

Disable presentation filters.


&disable_queued_filters=1

Metric Definitions

Understanding the metrics returned by the API.

General Metrics

Metric	Description
`nb_visits`	Number of visits (sessions)
`nb_uniq_visitors`	Number of unique visitors
`nb_users`	Number of identified users (with User ID)
`nb_actions`	Total actions (pageviews, downloads, etc.)
`bounce_count`	Number of bounced visits
`sum_visit_length`	Total visit duration in seconds
`max_actions`	Maximum actions in a single visit
`nb_visits_converted`	Visits with goal conversions
`nb_conversions`	Total goal conversions
`revenue`	Total revenue from goals

Page Metrics

Metric	Description
`nb_hits`	Number of page views
`entry_nb_visits`	Visits that started on this page
`exit_nb_visits`	Visits that ended on this page
`sum_time_spent`	Total time spent on page (seconds)
`bounce_rate`	Percentage of single-page visits
`exit_rate`	Percentage of visits that exited from this page
`avg_time_on_page`	Average time on page (seconds)

Event Metrics

Metric	Description
`nb_events`	Number of events
`nb_events_with_value`	Events with a value set
`sum_event_value`	Total of event values
`min_event_value`	Minimum event value
`max_event_value`	Maximum event value
`avg_event_value`	Average event value

Ecommerce Metrics

Metric	Description
`revenue`	Total revenue
`quantity`	Number of items sold
`orders`	Number of orders
`avg_price`	Average item price
`avg_quantity`	Average items per order

Processed Metrics

These are calculated metrics that may appear in responses:

Metric	Description
`bounce_rate`	`bounce_count / nb_visits`
`nb_actions_per_visit`	`nb_actions / nb_visits`
`avg_time_on_site`	`sum_visit_length / nb_visits`
`conversion_rate`	`nb_visits_converted / nb_visits`

Method-Specific Parameters

Some API methods accept additional parameters:

Goals Methods

Parameter	Description
`idGoal`	Specific goal ID
`abandonedCarts`	Include abandoned carts (1 or 0)

Live Methods

Parameter	Description
`lastMinutes`	Get data from last N minutes
`filter_limit`	Number of visitors to return

Actions Methods

Parameter	Description
`pageUrl`	Filter by specific URL
`pageName`	Filter by page title
`depth`	Depth of URL hierarchy

Next Steps

Segmentation — Filter with segments
Common Methods — Most-used API methods
Code Examples — Working implementations