---
title: "Fetch sessions"
method: POST
path: "/api/analytics/v1/sessions/"
tags: ["Analytics"]
---

# Fetch sessions

`POST /api/analytics/v1/sessions/`

API that allows fetching raw sessions from the database (event-level data
is not available in this API). Please note that each request must be
authenticated.

#### Compression

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

## Request body

- object
  - `website_id` string, uuid, required — ID of a website or a meta site.
  - `columns` object[], required — Definitions of additional columns that should be returned (timestamp and identifiers will be returned by default).
    - `column_id` string, required — ID of the dimension column.
    - `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).
  - `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 (inclusive, in website's timezone).
    - string, datetime — End datetime (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 dimension column.
      - `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``, ``starts_with``, ``ends_with``. ``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
  - `offset` integer — Number of rows to skip before beginning to return rows.
  - `limit` integer — Number of rows to return.
  - `format` 'json' | 'json-kv' | 'csv' — 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.

## Response `200`

OK

- object
  - `data` object[] — Rows with results for the query.
  - `meta` object — Additional results metadata for the query.
    - `columns` string[] — List of column IDs returned.
    - `count` integer — Total number of results available for this query.
    - `scope` 'session' — 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)