Execute query

post https://{account}.piwik.pro/api/analytics/v1/query/

API that allows querying the database directly. Please note that each
request must be authenticated.

Copy definition

You can use the View API call definition option
available in Analytics module in each report to get more
usage examples based on your existing reports.

View API call definition

Compression

When requesting large amount of data, make sure to include
an Accept-Encoding: gzip header to enable
compression.

Cache

Please note that all query results are cached for 10 minutes.

time	status	user agent
Retrieving recent requests…

Loading…

Body Params

website_id

string

required

ID of a website or a meta site.

columns

array of objects

required

Column definitions for the query.

columns*

date_from

string

Cannot be used with relative_date field at the same time. Mandatory if relative_date is not used.

date_to

string

Cannot be used with relative_date field at the same time. Mandatory if relative_date is not used.

relative_date

string

Use relative date in query. Cannot be used with absolute date fields at
the same time. X in last_X_days must be in range 1 <= X <= 365.
Note that last_X_days does not include data from today.
Mandatory if absolute date fields are not used.

filters

object

Dimension filters for the query. The top-level object must specify
AND/OR clause, but any nested objects may either specify another AND/OR
clause or a single filter.

metric_filters

object

Metric filters for the query. The top-level object must specify AND/OR
clause, but any nested objects may either specify another AND/OR
clause or a single filter.

offset

integer

≥ 0

Defaults to 0

Number of rows to skip before beginning to return rows.

limit

integer

1 to 100000

Defaults to 100

Number of rows to return.

order_by

array of arrays

Array of sorting directives. Each directive is a 2-element array with
0-based colum index and direction). You can sort on more than one column.
By default sorts descending by the first metric in query.

order_by

format

string

Defaults to json

Data format of a successful response (error responses are always in json).

column_format

string

Defaults to id

Format of the columns header (in CSV responses) and metadata labels
(in JSON responses). By default uses identifiers (id option), set to
name to use human-readable names.

options

object

Additional options for query.

Responses

Language

Credentials

OAuth2

URL


xxxxxxxxxx
18
1
curl --request POST \
2
     --url https://example.piwik.pro/api/analytics/v1/query/ \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json' \
5
     --data '
6
{
7
  "filters": {
8
    "operator": "and"
9
  },
10
  "metric_filters": {
11
    "operator": "and"
12
  },
13
  "offset": 0,
14
  "limit": 100,
15
  "format": "json",
16
  "column_format": "id"
17
}
18
'


xxxxxxxxxx
34
}
1
{
2
  "data": [
3
    [
4
      [
5
        "EU",
6
        "Europe"
7
      ],
8
      "Blink",
9
      529437,
10
      128334
11
    ],
12
    [
13
      [
14
        "NA",
15
        "North America"
16
      ],
17
      "Blink",
18
      199355,
19
      47171
20
    ],
21
    [
22
      [
23
        "AS",
24
        "Asia"
25
      ],

200OK

400Bad Request

401Unauthorized

403Forbidden

Get the full experience

Analytics