---
title: "Execute query"
method: POST
path: "/api/analytics/v1/query/"
tags: ["Analytics"]
---

# Execute query

`POST /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](https://ppdevelopersportal.z1.web.core.windows.net/assets/api-call-definition.png)


#### 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.

## Request body

- object
  - `website_id` string, uuid, required — ID of a website or a meta site.
  - `columns` object[], required — Column definitions for the query.
    - `column_id` string, required — ID of the column (either a dimension or a metric).
    - `transformation_id` string — Optional ID of the transformation. Must be supported by the column that was specified.
    - `goal_id` integer — Optional ID of a goal. Available only for metrics related to goals.
  - `date_from` union — Cannot be used with ``relative_date`` field at the same time. Mandatory if ``relative_date`` is not used.
    - string, date — Start date for the query (inclusive, in website's timezone).
    - string, datetime — Start datetime for the query (inclusive, in website's timezone).
  - `date_to` union — Cannot be used with ``relative_date`` field at the same time. Mandatory if ``relative_date`` is not used.
    - string, date — End date for the query (inclusive, in website's timezone).
    - string, datetime — End datetime for the query (exclusive, in website's timezone).
  - `relative_date` 'today' | 'yesterday' | 'last_week' | 'last_month' | 'last_year' | 'last_X_days' — 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.
    - `operator` 'and' | 'or', required — Logical operator (AND/OR) for the clause.
    - `conditions` object[], required — List of filters or recursively nested clauses.
      - `column_id` string, required — ID of the column (must be a dimension).
      - `transformation_id` string — Optional ID of the transformation. Must be supported by the column that was specified and must convert the column into another dimension (and not a metric).
      - `condition` object, required — Definition of a the condition for this column.
        - `operator` string, required — Filtering operator. Available choices depend on the specified column's type. String operators: ``eq``, ``neq``, ``contains``, ``not_contains``, ``icontains``, ``not_icontains``, ``starts_with``, ``ends_with``, ``matches``, ``not_matches``. For regular expressions (operators: ``matches`` and ``not_matches``) use [re2](https://github.com/google/re2/wiki/Syntax) syntax. Numeric operators: ``eq``, ``neq``, ``gt``, ``gte``, ``lt``, ``lte``. Boolean operators: ``eq``, ``neq``. Enum operators: ``eq``, ``neq``, ``empty``, ``not_empty``. IP operators: ``in_cidr``, ``not_in_cidr``. IPv4 and IPv6 are supported.
        - `value` unknown, required
  - `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.
    - `operator` 'and' | 'or', required — Logical operator (AND/OR) for the clause.
    - `conditions` object[], required — List of filters or recursively nested clauses.
      - `column_id` string, required — ID of the column (must be a metric, or a dimension converted to a metric).
      - `transformation_id` string — Optional ID of the transformation. Must be supported by the column that was specified and must convert the column into a metric.
      - `goal_id` integer — Specify a goal ID to calculate the metric using data limited to that goal only. Supported only by goal-related metrics.
      - `condition` object, required — Definition of a the condition for this column.
        - `operator` 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte', required — Filtering operator.
        - `value` number, float, required — Value that should be matched by filter.
  - `offset` integer — Number of rows to skip before beginning to return rows.
  - `limit` integer — Number of rows to return.
  - `order_by` array[] — 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.
    - union[]
      - union
        - integer
        - string
  - `format` 'json' | 'json-kv' | 'csv' | 'xml' — Data format of a successful response (error responses are always in json).
  - `column_format` 'id' | 'name' — 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.
    - `sampling` number, float — Apply sampling for query with given data percent. Sampling 0.1 means only 10% of data are used to calculate query results. Sampling 1 means that 100% of data is used to calculate results. Leave empty to apply default sampling value for this website. By default this means that sampling is turned off.

## Response `200`

OK

- object
  - `data` object[] — Rows with results for the query.
  - `meta` object — Additional results metadata for the query.
    - `count` integer — Total number of results available for this query.
    - `scope` 'session' | 'event' | 'product' | 'google ads map' | 'google ads stats' | 'google search console' — Information about used scope to calculate the report.
    - `blended_datasets` string[] — Information about used datasets to calculate the report.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden

---

[API](https://skmtc.net/piwik/apis/web-api.md) · [All operations](https://skmtc.net/piwik/apis/web-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/piwik/web-api/revisions/f63416a36168/schema)