Overview
Behavioral metrics are computed aggregations over a customer’s interaction history. They transform raw event data (impressions, clicks, conversions) into meaningful signals like “email frequency in the last 7 days” or “conversion rate for credit card offers.” These metrics power dynamic rules in contact policies, qualification, and scoring.
Key Fields
| Field | Type | Description |
|---|
name | string | Display name |
key | string | Unique machine-readable identifier |
aggregationType | enum | How events are aggregated |
eventType | string | The outcome type to aggregate (from outcome types) |
dimensions | string[] | Grouping dimensions (max 2) |
windowDays | number | Rolling time window in days (1-365) |
description | string | Human-readable description |
Aggregation Types
| Type | Description | Example |
|---|
count | Number of matching events | ”3 impressions in 7 days” |
sum | Sum of a numeric property on events | ”Total spend from conversions” |
avg | Average of a numeric property | ”Average order value” |
min | Minimum value | ”Lowest offer amount clicked” |
max | Maximum value | ”Highest offer amount converted” |
ratio | Ratio of two event types | ”Click-to-impression ratio” |
The ratio aggregation type requires a secondary event type. For example, a click-through rate metric would use click as the primary event and impression as the secondary event: count(click) / count(impression).
Dimensions
Dimensions control how the metric is grouped. You can specify up to 2 dimensions:
| Dimension | Description |
|---|
channel | Group by delivery channel (email, push, sms, etc.) |
offer | Group by specific offer |
- No dimensions: “Total clicks in 7 days” (single number per customer)
channel dimension: “Clicks per channel in 7 days” (one number per channel per customer)channel + offer dimensions: “Clicks per channel per offer in 7 days”
Time Window
The windowDays parameter defines the rolling lookback period:
- Minimum: 1 day
- Maximum: 365 days
- The window is always rolling — it looks back from the current moment
Limits
Each tenant can create a maximum of 20 behavioral metrics. This limit prevents excessive computation during decision time. Choose metrics that provide the most value for your decisioning rules.
Creating a Behavioral Metric
Navigate to Behavioral Metrics
Go to Studio > Behavioral Metrics in the sidebar.
Click Create Metric
Click the + New Metric button.
Name and key
Enter a display name and a unique key (e.g., email_freq_7d).
Select aggregation type
Choose from count, sum, avg, min, max, or ratio.
Select event type
Choose the outcome type to aggregate (impression, click, conversion, etc.). For ratio type, also select the secondary event type.
Set dimensions (optional)
Add up to 2 dimensions: channel, offer, or both.
Set time window
Enter the rolling lookback window in days (1-365).
Save
Save the metric. It begins computing immediately from existing interaction history.
Using Metrics in Rules
Behavioral metrics can be referenced in contact policies and qualification rules to create dynamic, data-driven decisioning.
Reference a metric in the config of a contact policy rule:
{
"name": "Dynamic Email Cap",
"ruleType": "frequency_cap",
"config": {
"metricKey": "email_impression_7d",
"threshold": 3,
"action": "suppress"
}
}
In Qualification Rules
Use a metric as a soft fit multiplier:
{
"name": "Engagement Score Gate",
"ruleType": "propensity_threshold",
"qualification": "soft",
"config": {
"metricKey": "response_rate_30d",
"threshold": 0.1,
"multiplierBelow": 0.3
}
}
Recipes
Common behavioral metric patterns for real-world use cases:
Frequency Cap
Conversion Cooldown
Channel Fatigue
Response Rate Gate
High-Value Targeting
Cross-Sell Detection
Metric: Count of impressions per channel in 7 days{
"name": "Channel Impression Count (7d)",
"key": "channel_impression_7d",
"aggregationType": "count",
"eventType": "impression",
"dimensions": ["channel"],
"windowDays": 7
}
channel_impression_7d > 3 for any channel. Metric: Count of conversions per offer in 30 days{
"name": "Offer Conversion Count (30d)",
"key": "offer_conversion_30d",
"aggregationType": "count",
"eventType": "conversion",
"dimensions": ["offer"],
"windowDays": 30
}
Metric: Count of dismiss events per channel in 14 days{
"name": "Channel Dismiss Count (14d)",
"key": "channel_dismiss_14d",
"aggregationType": "count",
"eventType": "dismiss",
"dimensions": ["channel"],
"windowDays": 14
}
Metric: Ratio of clicks to impressions in 30 days{
"name": "Click-Through Rate (30d)",
"key": "ctr_30d",
"aggregationType": "ratio",
"eventType": "click",
"secondaryEventType": "impression",
"dimensions": [],
"windowDays": 30
}
Metric: Sum of conversion values in 90 days{
"name": "Total Conversion Value (90d)",
"key": "conversion_value_90d",
"aggregationType": "sum",
"eventType": "conversion",
"dimensions": [],
"windowDays": 90
}
Metric: Count of conversions per offer category in 60 days{
"name": "Category Conversion Count (60d)",
"key": "category_conversion_60d",
"aggregationType": "count",
"eventType": "conversion",
"dimensions": ["offer"],
"windowDays": 60
}
API Reference
Create a Behavioral Metric
POST /api/v1/behavioral-metrics
Content-Type: application/json
{
"name": "Email Impression Count (7d)",
"key": "email_impression_7d",
"description": "Number of email impressions in the last 7 days",
"aggregationType": "count",
"eventType": "impression",
"dimensions": ["channel"],
"windowDays": 7
}
{
"id": "bm_email_impression_7d",
"name": "Email Impression Count (7d)",
"key": "email_impression_7d",
"description": "Number of email impressions in the last 7 days",
"aggregationType": "count",
"eventType": "impression",
"dimensions": ["channel"],
"windowDays": 7,
"createdAt": "2026-03-10T14:30:00Z",
"updatedAt": "2026-03-10T14:30:00Z"
}
List Behavioral Metrics
GET /api/v1/behavioral-metrics
Update a Behavioral Metric
PUT /api/v1/behavioral-metrics/:id
Delete a Behavioral Metric
DELETE /api/v1/behavioral-metrics/:id
Deleting a behavioral metric may break contact policies or qualification rules that reference it. Review dependent rules before deleting.
