Behavioral Metrics

Overview

Behavioral metrics let you define 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.” You use these metrics to power dynamic rules in contact policies, qualification, and scoring.

Field Reference

Field	Type	Required	Default	Description
`name`	string	Yes	—	Display name (1-100 characters)
`description`	string	No	`""`	Human-readable description (max 500 characters)
`aggregateFunction`	enum	Yes	—	Aggregation method: `count`, `sum`, `avg`, `min`, `max`, `ratio`
`sourceField`	enum	Yes	—	Outcome field to aggregate: `impressions`, `positive`, `negative`, `neutral`, `converts`, `totalValue`
`windowDays`	number	No	`null`	Rolling lookback window in days (1-365). Null means all-time
`groupByDimensions`	enum[]	No	`[]`	Grouping dimensions (max 2): `offerId`, `channelId`, `creativeId`, `outcomeType`
`filterConditions`	object	No	—	Nested filter with `and`/`or` logic and field-level operators (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `contains`)
`computeMode`	enum	No	`realtime`	How the metric is computed: `realtime` or `batch`
`batchIntervalMin`	number	No	—	Minutes between batch recomputations (5-1440, only used when `computeMode` is `batch`)
`status`	enum	Auto	`active`	Metric status: `active`, `paused`, `archived`

Aggregation Functions

Function	Description	Example
`count`	Number of matching records	”3 impressions in 7 days”
`sum`	Sum of the source field value	”Total spend from conversions”
`avg`	Average of the source field value	”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 function requires a secondary event type. For example, a click-through rate metric would use positive (clicks) as the source field and compute the ratio against impressions.

Source Fields

The sourceField determines which column of the outcome/interaction record is aggregated:

Source Field	Description
`impressions`	Count of impression events
`positive`	Positive outcomes (clicks, opens)
`negative`	Negative outcomes (dismissals, unsubscribes)
`neutral`	Neutral outcomes (views without action)
`converts`	Conversion events
`totalValue`	Monetary value associated with conversions

Dimensions

Dimensions control how the metric is grouped. You can specify up to 2 dimensions:

Dimension	Description
`offerId`	Group by specific offer
`channelId`	Group by delivery channel (email, push, sms, etc.)
`creativeId`	Group by creative variant
`outcomeType`	Group by outcome type (impression, click, conversion, etc.)

Examples:

No dimensions: “Total clicks in 7 days” (single number per customer)
channelId dimension: “Clicks per channel in 7 days” (one number per channel per customer)
channelId + offerId 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
Set to null or omit for an all-time aggregation
The window is always rolling — it looks back from the current moment

Compute Modes

Behavioral metrics support two compute modes that control freshness and performance characteristics:

Realtime Mode

When computeMode is realtime, the metric is recomputed on every decision request. The engine queries the interaction history at decision time, applies the aggregation, and returns the current value.

Freshness: Always up to date (includes events recorded moments ago)
Performance cost: Higher latency per decision request, especially for large interaction histories
Best for: Low-volume metrics, critical frequency caps, metrics that need sub-minute accuracy

Batch Mode

When computeMode is batch, the metric is precomputed on a schedule defined by batchIntervalMin. A background worker periodically aggregates all interaction data and stores the result. At decision time, the engine reads the precomputed value instead of querying raw events.

Freshness: Stale by up to batchIntervalMin minutes
Performance cost: Near-zero latency at decision time
Best for: High-volume metrics, long windows (90+ days), metrics where slight staleness is acceptable

Compute Mode	Freshness	Decision-Time Cost	Use Case
`realtime`	Instant	Higher	Frequency caps, real-time suppression
`batch`	Up to N minutes stale	Near-zero	Lifetime value, 90-day conversion rates

The batchIntervalMin field is only used when computeMode is batch. Valid values are 5 to 1440 minutes (5 minutes to 24 hours).

How Metrics Feed into Rules

Behavioral metrics are referenced in two key places during the decision pipeline:

In Qualification Rules (metric_condition)

A qualification rule of type metric_condition evaluates a behavioral metric against a threshold to determine whether an offer qualifies for a customer. The MetricConditionConfig specifies:

Field	Type	Description
`metricId`	string	UUID of the behavioral metric to evaluate
`operator`	enum	Comparison: `gt`, `gte`, `lt`, `lte`, `eq`
`threshold`	number	Value to compare the metric against
`dimensionMapping`	object	Maps metric dimensions to the current context (e.g., `{ "offerId": "{{offer.id}}" }`)

{
  "name": "Engagement Score Gate",
  "ruleType": "metric_condition",
  "qualification": "soft",
  "config": {
    "metricId": "bm_response_rate_30d",
    "operator": "gte",
    "threshold": 0.1,
    "dimensionMapping": {}
  }
}

When the metric value fails the threshold for a hard qualification rule, the offer is eliminated. For a soft rule, the offer receives a reduced score multiplier.

In Contact Policies

Contact policies reference metrics to enforce frequency caps and fatigue detection:

{
  "name": "Dynamic Email Cap",
  "ruleType": "frequency_cap",
  "config": {
    "metricKey": "email_impression_7d",
    "threshold": 3,
    "action": "suppress"
  }
}

When the metric value exceeds the threshold, the contact policy suppresses the offer on that channel.

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 describe

Enter a display name and description.

Select aggregation function

Choose from count, sum, avg, min, max, or ratio.

Select source field

Choose the outcome field to aggregate (impressions, positive, negative, neutral, converts, totalValue).

Set dimensions (optional)

Add up to 2 dimensions: offerId, channelId, creativeId, or outcomeType.

Set time window

Enter the rolling lookback window in days (1-365), or leave empty for all-time.

Choose compute mode

Select realtime for always-fresh values or batch for precomputed values with a refresh interval.

Add filter conditions (optional)

Define filter conditions to narrow which interaction records are included in the aggregation.

Save

Save the metric. It begins computing immediately from existing interaction history.

Recipes

Common behavioral metric patterns for real-world use cases:

Metric: Count of impressions per channel in 7 days

{
  "name": "Channel Impression Count (7d)",
  "aggregateFunction": "count",
  "sourceField": "impressions",
  "groupByDimensions": ["channelId"],
  "windowDays": 7,
  "computeMode": "realtime"
}

Usage: Create a contact policy that suppresses offers when channel_impression_7d > 3 for any channel.

Metric: Count of conversions per offer in 30 days

{
  "name": "Offer Conversion Count (30d)",
  "aggregateFunction": "count",
  "sourceField": "converts",
  "groupByDimensions": ["offerId"],
  "windowDays": 30,
  "computeMode": "realtime"
}

Usage: Suppress an offer for 30 days after a customer converts, preventing redundant recommendations.

Metric: Count of dismiss events per channel in 14 days

{
  "name": "Channel Dismiss Count (14d)",
  "aggregateFunction": "count",
  "sourceField": "negative",
  "groupByDimensions": ["channelId"],
  "windowDays": 14,
  "computeMode": "realtime"
}

Usage: If a customer dismisses 5+ offers on a channel in 14 days, reduce that channel’s priority with a soft fit multiplier.

Metric: Ratio of clicks to impressions in 30 days

{
  "name": "Click-Through Rate (30d)",
  "aggregateFunction": "ratio",
  "sourceField": "positive",
  "groupByDimensions": [],
  "windowDays": 30,
  "computeMode": "batch",
  "batchIntervalMin": 60
}

Usage: Use as a soft qualification rule — customers with low CTR get a reduced score multiplier.

Metric: Sum of conversion values in 90 days

{
  "name": "Total Conversion Value (90d)",
  "aggregateFunction": "sum",
  "sourceField": "totalValue",
  "groupByDimensions": [],
  "windowDays": 90,
  "computeMode": "batch",
  "batchIntervalMin": 120
}

Usage: Boost scoring for high-value customers by using this metric in the arbitration weighting.

Metric: Count of conversions per offer in 60 days

{
  "name": "Offer Conversion Count (60d)",
  "aggregateFunction": "count",
  "sourceField": "converts",
  "groupByDimensions": ["offerId"],
  "windowDays": 60,
  "computeMode": "batch",
  "batchIntervalMin": 60
}

Usage: Suppress offers in categories where the customer already converted recently, and boost cross-category offers.

API Reference

Create a Behavioral Metric

POST /api/v1/behavioral-metrics
Content-Type: application/json

Request body:

{
  "name": "Email Impression Count (7d)",
  "description": "Number of email impressions in the last 7 days",
  "aggregateFunction": "count",
  "sourceField": "impressions",
  "groupByDimensions": ["channelId"],
  "windowDays": 7,
  "computeMode": "realtime"
}

Response (201 Created):

{
  "id": "bm_email_impression_7d",
  "name": "Email Impression Count (7d)",
  "description": "Number of email impressions in the last 7 days",
  "aggregateFunction": "count",
  "sourceField": "impressions",
  "groupByDimensions": ["channelId"],
  "windowDays": 7,
  "computeMode": "realtime",
  "batchIntervalMin": 0,
  "status": "active",
  "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.

Get Started

Deploy & Operate

Runbooks

Data Platform

Decisioning Studio

Execute & Optimize

Intelligence

Platform & Security

Integrations

Reports

Release Notes

Behavioral Metrics

Overview

Field Reference

Aggregation Functions

Source Fields

Dimensions

Time Window

Compute Modes

Realtime Mode

Batch Mode

How Metrics Feed into Rules

In Qualification Rules (metric_condition)

In Contact Policies

Limits

Creating a Behavioral Metric

Recipes

API Reference

Create a Behavioral Metric

List Behavioral Metrics

Update a Behavioral Metric

Delete a Behavioral Metric

Next Steps

Algorithms & Models

Dashboards

Get Started

Deploy & Operate

Runbooks

Data Platform

Decisioning Studio

Execute & Optimize

Intelligence

Platform & Security

Integrations

Reports

Release Notes

​Overview

​Field Reference

​Aggregation Functions

​Source Fields

​Dimensions

​Time Window

​Compute Modes

​Realtime Mode

​Batch Mode

​How Metrics Feed into Rules

​In Qualification Rules (metric_condition)

​In Contact Policies

​Limits

​Creating a Behavioral Metric

​Recipes

​API Reference

​Create a Behavioral Metric

​List Behavioral Metrics

​Update a Behavioral Metric

​Delete a Behavioral Metric

​Next Steps

Algorithms & Models

Dashboards

Overview

Field Reference

Aggregation Functions

Source Fields

Dimensions

Time Window

Compute Modes

Realtime Mode

Batch Mode

How Metrics Feed into Rules

In Qualification Rules (metric_condition)

In Contact Policies

Limits

Creating a Behavioral Metric

Recipes

API Reference

Create a Behavioral Metric

List Behavioral Metrics

Update a Behavioral Metric

Delete a Behavioral Metric

Next Steps