Optional API parameters

Optional parameters in Piwik PRO API serve as filters either for data presentation (presentation filters) or data preprocessing (data helpers).

Presentation filters allow you to customize the display of your data.

With additional parameters you can perform initial data preprocessing like sorting, extracting a subset of data, fetch children of a given entity, etc.

Here you can find all optional parameters you may use while using the Piwik PRO API.

Translating output


This parameter, if specified, allows the API to return data strings that can be translated to other languages. This is especially useful when you have a report that will be presented to a multilingual audience.

With the language parameter, you can translate not only strings, but also, for example, dates.
Use two-character language codes for this parameter: en, de, pl, fr, es, etc.

Handling hierarchical data


Some data in Piwik PRO are hierarchical, as there are subtables attached to certain rows in main tables. While calling Piwik PRO API you can specify whether the output should include only first-level data or data including subtables. This parameter can take values of 0 (false) or 1 (true). If ‘expanded=1’ then the API call will return results with subtables.


A subtable is a table linked to row in a higher-level table. For example: each row in the Referrers.getSearchEngines response has an “idsubdatatable” field. This integer idsubdatatable is the idSubtable of the table that contains all the keywords for this search engine. You can then request the keywords for this search engine by calling Referrers.
Example: getKeywordsFromSearchEngineId with the parameter idSubtable=X (replace X with the idsubdatatable value found in the Referrers.getSearchEngines response, for the search engine you are interested in).


This parameter, also used for hierarchical data, allows you to retrieve hierarchical data as a flat output. If ‘flat=1’, the returned data will contain the flattened view of the table data set. The children of all first level rows will be aggregated as separate rows.
Example: this is useful to see all Custom Variable names and values at once like for Piwik forum user status, or to see the full URLs not broken down by directory or structure.

Pivoting data


This parameter can be used to create a pivot table of a report using a specified dimension.

Pivoting a report will intersect a report with another one and display a single metric for values along two dimensions.
To pivot a report, this query parameter must be set to the ID of the dimension to pivot by. For example, pivotBy=Referrers.Keyword would pivot against the Keyword dimension.

Note: If you want to pivot against a dimension that is not the dimension of a report’s subtable, you must set the pivot_by_filter_enable_fetch_by_segment INI config variable to 1. Using segments will allow you to pivot by any dimension, but currently it is a slow operation.


This parameter specifies which column should be displayed in a pivoted report. It should be used with pivotBy and set to a column name, for example, nb_visits.


This parameter can be used to specify the maximum number of columns that should be displayed in a pivot table. All other columns are aggregated into an ‘Others’ column.

Filtering data


This parameter can be used to define the offset of the starting row being returned by the API call.


This parameter defines the number of rows to be returned by the API call. By default it only returns the first 100 rows, while setting it to -1 will return all rows.


Setting this parameter will truncate the table after $filter_truncate rows. The last row will be named ‘Others’ (localized in the requested language) and the columns will be an aggregate of statistics of all truncated rows


This parameter will help you to search for the row matching a specific label, filter it, and retrieve only that row.
Example: &label=best%20hotdogs

This will return only the row with the label “best hotdogs”

In the Piwik PRO API there are also generic filters you can choose to apply on all APIs that return web analytics reports. For example, there is a filter for sorting by column – you define the start and number of rows to return. There is also a filter to only return rows matching a given string.


This parameter defines the text you want to search for in the filter_column. Only the row with the given column matching the pattern will be returned. The pattern will be interpreted as a regular expression.
Example: (en|pl|de)\.mydomain.


This parameter defines the column where you want to search for the text in filter_pattern. If not specified, defaults to ‘label’ (label).


This parameter defines the order of the results. Can take values ‘asc’ or ‘desc’.


This parameter defines the column for data to be sorted by.


This parameter defines the column to use for the threshold of the value filter_excludelowpop_value. Only the columns with a value greater than filter_excludelowpop_value will be returned.


This parameter defines the minimum value for the filter_excludelowpop column.


This parameter defines the column to be searched for when recursively searching for the pattern filter_pattern_recursive.


This parameter defines the text you are searching for and is applied to recursive tables (Actions/Downloads/Outlinks tables).


This parameter turns off all the generic filters above, if set to 1. This can be useful to disable the filters above which are otherwise applied with default values.


This parameter, if set to 1, turns off all the filters that are mostly presentation filters (replace a column name, apply callbacks on the column to add new information such as the browser icon URL, etc.). Mostly used internally or when developing plugins for Piwik PRO.


This parameter takes a comma-separated list of columns. If set, it removes the specified columns from the result.


This parameter takes a comma separated list of columns. If set, it removes all columns not specified in this list from the result.

Both parameters above can be used to reduce the amount of data transferred.

Was this article helpful?

of people found this helpful

Technical Support

If you have any questions, drop us a line at support_SPC@piwik_SPC.pro.

We’re happy to help!