Build audiences
Metrics
Per-customer values kept current by events: counts, totals, last-seen times, latest values and lists.
A metric is a value kept per customer and updated by events, such as total_spend or last_order_at. Metrics are what segments are built on: decide what you want to target, then define the metrics that measure it.
You define a metric once as a metric definition (also called a claim): "metric M is fed by event E, reading the value at path P". BreezeIQ then keeps it current for every customer. To create and list definitions, see the Metric definitions API.
Value kinds#
value_kind | What the metric holds | Example |
|---|---|---|
count | Number of events | order_count on purchase |
property_number | Sum of a number in the event, read at value_path | total_spend = sum of properties.amount |
occurred_at_epoch | Time of the most recent event (Unix seconds) | last_order_at, last_checkout_at |
property_string + "aggregation": "latest" | The newest text value (newest by event time) | country, last_payment_method |
property_string + "aggregation": "recent" | The newest keep distinct values, newest first (keep 1–10, default 5) | recent_cart_adds = the last 5 products added |
Rolling windows#
Limit count and property_number to a rolling window with window_days (1–730), for example spend_last_30d. The value goes down by itself as old events fall out of the window.
Value paths#
value_path is a dotted path from the event root, starting with properties.. For this event, properties.amount reads 2499 and properties.shipping.country reads "IN".
{
"name": "purchase",
"properties": {
"amount": 2499,
"shipping": { "country": "IN" }
}
}Text and list metrics#
- Text values are trimmed and capped at 128 characters. Numbers and true/false become text. Empty values, objects and arrays are skipped.
- On a profile, a
latestmetric carries"text"and arecentmetric carries"items", each item with the time it was last seen. - Their numeric
valueis the time of the newest value.
"metrics": [
{
"metric": "total_spend",
"display_name": "Total spend",
"value": "4998",
"stamped_version": 3
},
{
"metric": "country",
"display_name": "Country",
"value": "1791364450",
"text": "IN",
"stamped_version": 3
},
{
"metric": "recent_cart_adds",
"display_name": "Recent cart adds",
"value": "1791370287",
"stamped_version": 3,
"items": [
{ "value": "SKU-7", "at": "2026-10-07T10:51:27Z" },
{ "value": "SKU-6", "at": "2026-10-07T10:51:22Z" },
{ "value": "SKU-5", "at": "2026-10-07T09:14:30Z" }
]
}
]In segments#
Because value is a time, segments can ask "added to cart in the last day" (within_days) or whether the metric exists at all. Matching on the text itself (for example country = "IN") isn't supported in segments yet; read it from the profile instead.
Rules#
A new metric counts events received after it is defined; history isn't backfilled. To include older activity, resend those events with their original occured_at. Deduplication keeps events that were already counted from counting twice.
To change one, delete it and create it again, or use a new metric name, so existing totals never silently change meaning.
One metric, several events#
To feed one metric from several events, create one metric definition per event with the same metric_name. For example, last_seen_at fed by both purchase and initiatecheckout.