---
title: "Fetch Real-time events"
method: POST
path: "/api/analytics/v1/real-time-events/"
tags: ["Analytics"]
---

# Fetch Real-time events

`POST /api/analytics/v1/real-time-events/`

API that allows fetching raw Real-time events from the database.
Real-time data is retained for only an hour and may be available with a slight delay (up to a couple of minutes),
so we highly recommend getting the data older than 3 minutes (and newer than 60).

This API is not suitable for feeding external data warehouses as it is not a reliable source of complete data
\- for that purpose we recommend regular [Raw data API](/reference/post_api-analytics-v1-events) or Exports.

Please note that each request must be authenticated.

## Request body

- object
  - `website_id` string, uuid, required — ID of a website.
  - `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` string, datetime, required — Start datetime for the query (inclusive, in website's timezone).
  - `date_to` string, datetime, required — End datetime for the query (exclusive, in website's timezone).
  - `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` 'Real-time event' | 'Real-time product' — 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)