Summary Definitions

See also: Summary Definitions REST API reference for request/response shapes, status codes, and error semantics.

Overview

Summary definitions let you control exactly how interaction data is aggregated. Instead of a fixed set of rollup tables, you define the dimensions, aggregates, and time windows that matter to your business. The platform materializes these summaries continuously as interactions flow in, so they are always ready for fast reads at decision time and in dashboards. Each summary definition is a named aggregation shape consisting of three parts:

Dimensions — What to GROUP BY
Aggregates — What to compute
Windows — Rolling time periods to maintain

Dimensions

Dimensions determine the grouping keys for each summary row. You can select one or more of the following:

Dimension	Description
`offer_id`	Group by Offer
`creative_id`	Group by Creative
`category_id`	Group by Category
`sub_category_id`	Group by Sub-Category
`channel_id`	Group by Channel
`placement_type`	Group by placement (e.g. banner, inline, push)
`direction`	Group by direction (inbound vs outbound)
`outcome_key`	Group by outcome type (impression, click, conversion, etc.)

Start with fewer dimensions and add more only when needed. Each additional dimension multiplies the number of summary rows the system must maintain.

Aggregates

Aggregates define the values computed for each group. The following aggregate types are available:

Aggregate	Description
`count`	Number of interactions in the group
`sum_value`	Sum of the `value` field across interactions (e.g. revenue, spend)
`last_contact`	Timestamp of the most recent interaction
`distinct_offers`	Count of distinct Offer IDs (useful when grouping by channel or category)

You can select multiple aggregates in a single summary definition. All selected aggregates are computed for every dimension combination.

Windows

Windows define the rolling time periods over which aggregates are maintained. You can select one or more windows per summary definition:

Window	Period
`1d`	Last 24 hours (1 day)
`7d`	Last 7 days
`14d`	Last 14 days
`30d`	Last 30 days
`90d`	Last 90 days

How Rolling Windows Work

Summary definitions use a daily bucket approach for rolling windows:

Interactions are bucketed by calendar day (UTC).
At read time, the system SUMs the daily bucket rows that fall within the requested window.
This approach is exact — no approximation or sampling.
Old daily buckets are retained indefinitely (no TTL), which means you can always redefine windows without losing data.

Because rolling windows are computed at read time by summing daily buckets, changing a window value (e.g. from 7d to 14d) takes effect immediately with no reprocessing required.

System Defaults

Every tenant is automatically provisioned with three default summary definitions. These cover the most common analytics needs and are used by built-in dashboards and contact policy evaluation:

Default Summary	Dimensions	Aggregates	Windows
Offer Interactions	`offer_id`, `channel_id`, `outcome_key`	`count`, `sum_value`, `last_contact`	`1d`, `7d`, `30d`
Category Outcomes	`category_id`, `outcome_key`	`count`, `sum_value`, `distinct_offers`	`7d`, `30d`, `90d`
Channel Performance	`channel_id`, `direction`, `outcome_key`	`count`, `sum_value`, `last_contact`	`1d`, `7d`, `30d`

System default summaries cannot be deleted, but you can modify their dimensions, aggregates, and windows if the defaults do not suit your needs.

API Reference

Method	Endpoint	Description
GET	`/api/v1/summary-definitions`	List all summary definitions for the tenant
POST	`/api/v1/summary-definitions`	Create a new summary definition
PUT	`/api/v1/summary-definitions`	Update an existing summary definition (requires `id` in body)
DELETE	`/api/v1/summary-definitions?id={id}`	Delete a summary definition

Create Example

POST /api/v1/summary-definitions

{
  "name": "Creative Placement Performance",
  "description": "Tracks creative performance by placement type and outcome",
  "dimensions": ["creative_id", "placement_type", "outcome_key"],
  "aggregates": ["count", "sum_value", "last_contact"],
  "windows": ["1d", "7d", "30d"]
}

Response:

{
  "id": "sd_creative_placement",
  "name": "Creative Placement Performance",
  "description": "Tracks creative performance by placement type and outcome",
  "dimensions": ["creative_id", "placement_type", "outcome_key"],
  "aggregates": ["count", "sum_value", "last_contact"],
  "windows": ["1d", "7d", "30d"],
  "isSystemDefault": false,
  "createdAt": "2026-03-26T10:00:00Z",
  "updatedAt": "2026-03-26T10:00:00Z"
}

Use Case: Creative Placement Performance

Suppose you run creatives across multiple placement types (banner, inline, push notification) and want to understand which creative/placement combinations drive the most conversions:

Create a summary definition with dimensions creative_id, placement_type, outcome_key.
Select aggregates count and sum_value to track volume and revenue.
Choose windows 7d and 30d for weekly and monthly views.
The platform immediately begins materializing rows for this shape as new interactions arrive.
Query the data via dashboards or the interaction summary API, grouped by your chosen dimensions.