Documentation

Overview

The KPI Scorecard widget displays a single metric value at a glance — formatted as a number, currency, or percentage — alongside a period-over-period comparison and trend indicator. Add it to any dashboard to surface key performance metrics quickly.

This guide covers all KPI Scorecard configuration options from basic setup to custom metrics.

What's in this guide

1. Adding a KPI Scorecard Widget
2. Selecting Metrics
3. Aggregation Method
4. KPI Display Types
5. Period-over-Period Comparison
6. Custom Metrics

1. Adding a KPI Scorecard Widget

Follow these steps to place a KPI Scorecard on your dashboard.

1. Open your dashboard in edit mode. A toolbar with available widget types appears at the bottom of the canvas.
2. Connect a data table. Click the Select a default data table dropdown in the header bar and choose your data source (for example, cross_channel_automated_recipe). Wait a moment for the list to load.
3. Click + KPI Scorecard in the bottom toolbar. The widget appears on the canvas and the Properties Panel slides in from the right automatically.
4. Set a title (optional). In the Basics section of the Properties Panel, fill in the Widget Title field.
5. Select a metric. Expand the Data section and click a metric. The KPI renders immediately with the selected value.
6. Close the Properties Panel by clicking the X icon to view the full widget display.

2. Selecting Metrics

The KPI displays a single metric value at a time.

1. Open the Data section in the Properties Panel.
2. Click a metric to select it. The widget renders the value immediately. Standard metrics (Spend, Clicks, Impressions) and calculated metrics (ROAS, CTR, CPC, CPM, CPA, Conversion Rate) are both supported.
3. Switch metrics by clicking a different one. The active metric appears in the Selected Metric area at the top of the Data section.

Note: The value is automatically formatted based on the metric type — dollar amounts for spend, percentages for rates, and ratios for calculated metrics like ROAS.

3. Aggregation Method

By default, the KPI aggregates the selected metric using Sum over the current date range. You can change this per metric.

1. Select a metric in the Data section.
2. Click the expand button (chevron icon) next to the metric name in the Selected Metric area. Additional options appear: Decimals, Rounding, Format, Total, Sparkline, Prefix, and Suffix.
3. Click the Total: dropdown and choose an aggregation method.

4. KPI Display Types

The KPI Scorecard supports three visual layouts. Find the type selector in the Basics section of the Properties Panel.

Note: Select a metric before switching types to see the full effect of each layout.

5. Period-over-Period Comparison

The KPI Scorecard automatically compares the current period value to the equivalent previous period.

• The comparison appears below the main value (for example, +57.5% vs previous 30 days).
• A trend indicator shows the direction: a green upward arrow for a positive change and a red downward arrow for a negative change.
• The comparison period automatically matches the selected date range — switching to Last 7 Days updates the comparison to vs previous 7 days.

Note: Comparison is not available when the date range is set to All Time, as there is no equivalent previous period.

6. Custom Metrics

Create a custom metric to display a derived value not available in the standard metric list.

1. Scroll to Custom Metrics in the Data section of the Properties Panel.
2. Click the + button next to Custom Metrics. The Add Custom Metric dialog opens.
3. Fill in the dialog: enter an optional Name, select a Type (Simple or Custom SQL), and for Simple type choose a Field and confirm the Aggregation (defaults to Sum).
4. Click Add. The dialog closes and the new metric is automatically selected as the active KPI metric.
5. Save the dashboard. Custom metrics persist after saving and reloading the page.