Widget types

Widgets are the main building blocks of a dashboard in Metriox. Each widget type is designed for a specific kind of analysis.

Metriox has 9 report types, but they are reached in different ways. Six are added to a dashboard as cards (Top, Funnel, Table, KPI, Histogram, Series). The other three — Heatmap, Retention and Cohort — live on their own pages and cannot be added to a dashboard: Heatmap on the Audience page, Retention and Cohort on the pages of the same name. All nine are described below.

1. Top

Ranks events or properties by how often they occur.

When to use it:

• Top 10 most popular events
• Most active users
• Popular screens or features

Settings:

• Metric: Events, Users, Events per User
• Grouping: by event or property
• Limit: number of items (5, 10, 20, 50)

Example:

The "Top country" widget shows the leading countries: RU — 27, NL — 5, DE — 2, and 1 each for US, LV, and FI.

The same data can be rendered as a pie chart — an alternative visualization of the same Top widget that shows each value's share as a percentage.

Visualization:

• Bar chart
• Pie chart
• Table with percentages

---

2. Funnel

Analyzes a sequence of events and the conversion between steps.

When to use it:

• Purchase funnel
• User onboarding
• Multi-step processes

Settings:

• Funnel steps: a sequence of events (at least 2)
• Time window: the time allowed between steps (1 hour, 1 day, 7 days)
• Metric: Users (unique users)

Example:

A three-step funnel: Start — 514 users, Trial — 102 (19.84%), Buy — 37 (7.19%). The From previous column shows conversion from the preceding step, From start — from the first step of the funnel.

Visualization:

• Classic funnel with percentages
• Table with absolute and relative values

---

3. Table

Shows detailed data in tabular form.

When to use it:

• Detailed property analysis
• Comparing several metrics
• Exporting data

Settings:

• Rows: grouped by event or property
• Columns: metrics (Events, Users, Events per User)
• Sorting: by any column
• Filters: limit which rows appear

Example:

Event	Events	Users	Events/User
button_click	15,432	3,214	4.8
screen_view	12,891	2,987	4.3
purchase_started	3,456	1,234	2.8
message_sent	2,105	876	2.4

Visualization:

• Interactive table
• Sorting and pagination support

---

4. KPI

Displays a single metric value — one key performance indicator.

When to use it:

• A key product metric
• The current value of an important indicator
• Quick monitoring

Settings:

• Metric: Events, Users, Events per User
• Filters: narrow down by event or property
• Comparison: against the previous period (optional)

Example:

A widget with the MAU metric: one large number — 28.

Visualization:

• A large number
• Percentage change with a trend icon

---

5. Histogram

A two-dimensional histogram of value distribution.

When to use it:

• Distribution across hours of the day
• Grouping by numeric properties
• Analyzing activity patterns

Settings:

• X axis: a time or numeric range
• Y axis: metric (Events, Users)
• Buckets: how values are grouped (hours, intervals)

Example:

Values distributed across buckets with a step of 30 — from 0–30 to 720–750. The largest bucket is 150–180 (122); the smallest are 60–90 (8) and 420–450 (12).

Visualization:

• Bar chart
• Heatmap

---

6. Series

A chart of how a metric changes over time.

When to use it:

• Activity dynamics
• Trends by day or week
• Comparing periods

Settings:

• Metric: Events, Users, Events per User
• Granularity: minute, hour, day, week, month
• Lines: one or several metrics
• Smoothing: moving average (optional)

Example:

A time series with hourly granularity: activity stays at its minimum overnight, climbs from 08:00, and peaks around 13:00.

Visualization:

• Line chart
• Area under the line
• Several lines for comparison

---

7. Heatmap

Shows how activity is distributed across a two-dimensional grid: weekday and hour of day, or day of month and hour of day.

When to use it:

• Find peak hours of user activity
• Plan broadcasts and notifications
• Spot time-based behavior patterns

Settings:

• Mode: weekday × hour (WeekdayHour) or day × hour (DayHour)
• Metric: Events, Users, Events per User
• Time zone: so values line up with local time

Example:

Activity level by weekday and hour of day. In the interface these levels are shown with color: the darker the cell, the higher the activity.

Weekday	00	02	04	06	08	10	12	14	16	18	20	22
Mon	low	low	low	low	medium	high	high	high	high	high	medium	low
Tue	low	low	low	low	medium	high	high	high	high	high	medium	low
Wed	low	low	low	low	medium	high	high	high	high	high	medium	low
Thu	low	low	low	low	medium	high	high	high	high	high	medium	low
Fri	low	low	low	low	medium	high	high	high	high	high	medium	low
Sat	low	low	low	low	low	medium	medium	medium	medium	low	low	low
Sun	low	low	low	low	low	medium	medium	medium	medium	low	low	low

Visualization:

• Color scale: the darker the cell, the more activity

---

8. Retention

Shows what percentage of users come back to the bot N days after their first visit.

Each column is one period: Day 7 means "came back on day 7 exactly", not "within 7 days". For cumulative "within N days" figures, see the Vitals page.

When to use it:

• Measure user retention (D1, D7, D30)
• Compare retention across cohorts
• Assess how changes affect return rates

Settings:

• Start event: any event (all users) or a specific event selected by filter
• Return event: any event (all users) or a specific event selected by filter
• Grouping: the calendar unit for cohorts and return steps — day, week, or month (weeks start on Monday)
• Observation window: how many grouping units to track returns for (for example, 30 days, 12 weeks, or 12 months)

Example:

A cohort table with daily granularity: each row is a cohort, and the Day 0 … Day 13 columns show the share of users who returned. The deeper the green, the higher the retention.

The widget's settings live in the Retention Configuration panel: there you choose the start and return events (Start Event and Return Event) and a shared filter (Global Filter). Below it are the same cohorts with weekly granularity, Week 0 … Week 7.

Visualization:

• A cohort table with a color scale based on retention percentage

---

9. Cohort

Groups users by the date they first appeared and shows the size of each cohort.

When to use it:

• Track audience growth by cohort
• Compare cohort sizes before and after a change
• Analyze seasonality in user acquisition

Settings:

• Start event: any event (all new users) or a specific event selected by filter
• Bucket size: the grouping interval (for example, 7 = weekly cohorts)

Example:

Cohort	New users
01–07 Apr	1 200
08–14 Apr	1 450
15–21 Apr	1 100
22–28 Apr	980

Visualization:

• A bar chart or a table by period

---

Common widget settings

The settings below apply to dashboard cards. Heatmap, Retention and Cohort have their own set on their respective pages — for Retention, that is the cohort size and the return event.

Time range

• Last 1 hour / 6 hours / 24 hours
• Last 7 days / 14 days / 30 days / 90 days
• Custom period

Granularity

For the Series widget only. Histogram groups by the value of a numeric property, not by time.

Granularity sets the size of the time bucket events are grouped into. Each one has its own maximum period: the finer the bucket, the shorter the stretch of time you can ask for at once.

Granularity	Maximum period	Points at the maximum
Minute	2 hours	120
Hour	90 days	2,160
Day	370 days	370
Week	1,100 days (about 3 years)	157
Month	1,830 days (about 5 years)	60

The limits exist so that a single request cannot ask for an unbounded number of points. A request whose period exceeds its granularity's maximum is refused with a 400 and a message naming the limit itself — for example Minute granularity is limited to 02:00:00. That is a deliberate refusal rather than a failure: the chart declines to load instead of taking a very long time to.

Weeks start on Monday (UTC), matching the Retention cohorts and the Vitals calendar periods, so that "a week" means the same thing everywhere. Months are calendar months, starting on the 1st.

Auto

The default. The server picks the finest granularity that yields no more than 400 points without exceeding that granularity's maximum period:

Requested period	Granularity	Points
up to 400 hours (about 16.5 days)	Hour	up to 400
16.5 to 370 days	Day	up to 370
370 to 1,100 days	Week	up to 157
1,100 to 1,830 days	Month	up to 60

Two different rules set those boundaries, and the distinction is worth knowing. The Hour → Day switch is set by the 400-point target: 400 hours is roughly 16.5 days. The Day → Week switch is not set by the target at all but by Day's maximum period — at 370 days that is only 370 points, still under the target, but Day is not permitted to reach further. That is why a year of data stays daily rather than becoming weekly.

Auto never picks Minute — ask for it explicitly if you want it.

The granularity actually used is always returned in the response as usedGranularity, so you can tell what was built even when Auto made the choice.

Filters

Every widget supports filtering:

• By event
• By event property
• Combinations of conditions (AND/OR/NOT)

Learn more: Filters

Metrics

The metrics available depend on the widget type:

• Events — the number of events
• Users — the number of unique users
• Events per User — the average number of events per user

Learn more: Metrics

---

Usage examples

Activity monitoring

A combination of widgets:

1. KPI: active users for the day
2. Series: DAU over the month
3. Top: top 10 events

Purchase funnel analysis

A combination of widgets:

1. Funnel: the funnel from start to purchase
2. Table: a breakdown by step
3. Series: conversion dynamics by day

Engagement analysis

A combination of widgets:

1. Histogram: activity distribution by hour
2. Series: Events per User by day
3. Top: most engaged users

---

Best practices

Choosing a widget type

• Top — for rankings and popularity
• Funnel — only for sequential processes
• Table — when you need detail and export
• KPI — for a single important metric
• Histogram — for distributions of numeric properties
• Series — for trends over time
• Heatmap — for activity patterns by hour and day
• Retention — for measuring user retention
• Cohort — for analyzing growth and user acquisition

Configuring widgets

• Use meaningful names: "Purchase conversion" rather than "Funnel 1"
• Adjust colors for readability
• Add descriptions to your widgets
• Group related widgets on the same dashboard

Performance optimization

• Avoid very long time ranges with minute granularity
• Use filters to limit the data
• Don't create too many widgets on one dashboard (4-8 works best)

---

What's next?

• Dashboard overview — creating and organizing dashboards
• Filters — learn to filter data inside widgets
• Metrics — find out more about metrics