> For the complete documentation index, see [llms.txt](https://docs.mediarithmics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediarithmics.io/setup-and-monitor/operate-and-monitor/query-your-datamart/data-cube-activities-analytics.md).

# Data cube (Activities Analytics)

Query user activities as a data cube: metrics, dimensions, filters, and date ranges.

## Your goal

Answer analytical questions about behaviour - active users, sessions, transactions - by combining metrics, dimensions, and filters rather than writing a query per question.

## Expected outcome

Reports you can parameterise and reuse, including behind dashboards.

## What a data cube is

Several API endpoints give access to **data cubes**. In each of them you create a **report** with a specific set of metrics and dimensions defined for that cube.

| Cube                            | What it returns                                                                                                                                     |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Activities analytics**        | Information on UserActivity.                                                                                                                        |
| **Collection volumes**          | The number of indexed objects at given times. See [Monitor collection volume](/setup-and-monitor/operate-and-monitor/monitor-collection-volume.md). |
| **Events ingestion monitoring** | Events reaching each pipeline step. See [Monitor data ingestion](/setup-and-monitor/operate-and-monitor/monitor-data-ingestion.md).                 |
| **Resources usage**             | Query cost and ingested volume. See [Monitor resource usage](/setup-and-monitor/operate-and-monitor/monitor-resource-usage.md).                     |

They all take the same request shape, which is why learning one teaches you the others.

## Activities analytics

This API gives programmatic access to user activities as a data cube: metrics, with dimensions, filters, and date ranges - leveraging the [activities analytics](/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time/activities-analytics.md) part of the multi-model database.

```
POST https://api.mediarithmics.com/v1/datamarts/:datamartId/user_activities_analytics
```

{% hint style="info" %}

* Maximum recommended rate: **5 queries per second**.
* Response time: around **1 second**.
* Results cover the **4 latest months** - the retention of activities analytics data.
  {% endhint %}

## Questions it answers

The pattern is always the same: a **metric**, optional **dimensions** to group by, and optional **filters**.

| Question                                                                 | Metric                   | Dimensions                    | Filters                                                                                |
| ------------------------------------------------------------------------ | ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------- |
| Number of active users                                                   | `users`                  | -                             | -                                                                                      |
| Number of active users per channel per day                               | `users`                  | `channel_id`, `date_yyyymmdd` | -                                                                                      |
| Sessions per day for users who had an `AD_VIEW` activity on campaign 666 | `sessions`               | `date_yyyymmdd`               | `activity_type = AD_VIEW`, `origin_campaign_id = 666`                                  |
| Days with more than 200k transactions on a channel                       | `number_of_transactions` | `date_yyyymmdd`               | `channel_id = 666`, plus a filter on the **calculated metric** to keep days above 200k |

That last row is worth noting: filters apply both to dimensions **before** the metric is calculated, and to the calculated metric itself.

## The request

| Field                      | Description                                                         |
| -------------------------- | ------------------------------------------------------------------- |
| `metrics`                  | The metrics to retrieve.                                            |
| `dimensions`               | The dimensions to group metrics by.                                 |
| `dimension_filter_clauses` | Filters applied on dimensions **before** the metric is calculated.  |
| `date_ranges`              | The periods to analyse, each with a `start_date` and an `end_date`. |

```json
{
    "date_ranges": [
        { "start_date": "now-30d/d", "end_date": "now/d" }
    ],
    "dimensions": [
        { "name": "channel_id" },
        { "name": "date_yyyymmdd" }
    ],
    "metrics": [
        { "expression": "users" }
    ]
}
```

The response is a report view with `columns_headers` and `rows`.

## Where the data comes from

The cube reads the **duplicated and optimised** copy of your activities that the platform maintains for performance analytics - and that copy is only built for **predefined events**.

{% hint style="danger" %}
If a metric returns zero where you expect volume, the cause is usually upstream: your events use **custom names** rather than predefined ones, so they were never copied into the analytics store.

See [Standard events](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/standard-events.md) and, if you cannot change your tracking, [event transformations](/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time/activities-analytics.md#transforming-your-custom-events).
{% endhint %}

## Where it is used

* Directly, through the API, for reporting.
* Behind [custom dashboards](/setup-and-monitor/operate-and-monitor/create-a-custom-dashboard.md).
* In the built-in dashboards and funnel analytics.

## Related pages

<table data-view="cards" data-search="false"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Activities analytics</strong></td><td>How the analytics store is built, and its retention.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time/activities-analytics.md">Activities analytics</a></td></tr><tr><td><strong>Create a custom dashboard</strong></td><td>Putting cube reports in front of your teams.</td><td><a href="/setup-and-monitor/operate-and-monitor/create-a-custom-dashboard.md">Create a custom dashboard</a></td></tr><tr><td><strong>OTQL</strong></td><td>For questions about users rather than aggregated behaviour.</td><td><a href="/setup-and-monitor/operate-and-monitor/query-your-datamart/otql.md">OTQL</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mediarithmics.io/setup-and-monitor/operate-and-monitor/query-your-datamart/data-cube-activities-analytics.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.