Summarize delivered value
Aggregates delivered value into period buckets for charting value over time, grouped by value metric, by a signal-payload key (for example, value delivered per team_id), or by the formula condition band that priced each row (for example, value delivered per workflow complexity). Any grouping can be narrowed to a single value metric, which is also what lets a dimension grouping state a unit total. Reads the same rows as GET /delivered-value, so summing every bucket’s monetaryTotal matches that endpoint’s total for the same customer and window. Figures always reflect the currently active value model. Shortly after you publish a model change, totals can still be priced under the previous model’s rates. Grouping by band reads a figure recorded when the row was priced, so value delivered before this grouping existed reports under the “none” band until a value-model backfill re-derives it.
Authentication
Query parameters
The customer to summarize delivered value for. Accepts a Paid customer ID or, as a fallback, your external customer ID. Mutually exclusive with externalCustomerId; exactly one is required.
Your external customer ID. Mutually exclusive with customerId; exactly one is required.
Window start, inclusive. Accepts an ISO 8601 date or date-time. Date-only values (e.g. 2026-06-30) are treated as UTC; date-times without an explicit timezone offset are ambiguous, so include one (e.g. 2026-06-30T00:00:00-05:00) when precision matters.
Window end, inclusive — a date-only value means through the end of that UTC day. Accepts an ISO 8601 date or date-time. Date-only values (e.g. 2026-06-30) are treated as UTC; date-times without an explicit timezone offset are ambiguous, so include one (e.g. 2026-06-30T00:00:00-05:00) when precision matters.
How to group the buckets. valueMetric groups by the value metric that delivered the money. dimension groups by a signal-payload key named in dimensionKey, summed across metrics unless valueMetric narrows it to one — for example, value delivered per team when your signals carry a team_id field. formulaCondition cuts each metric by the condition band that priced it, for a value model that prices in graduated bands — for example, value delivered per workflow complexity when the metric bands runs by step count. A band the window never hit still reports a zero in every period, so the series keeps its shape.
The signal-payload key to group by (up to 64 letters, digits, or underscores). Required when groupBy is dimension; rejected otherwise. A signal whose payload lacks the key, or holds it empty, groups under an empty groupKey.
Narrow the summary to a single value metric, by slug. Every grouping accepts it: it restricts which rows are read, so the totals are that metric’s alone. Under groupBy=dimension it is also what makes unitTotal stateable — one metric is one unit, where a sum across metrics is in none. An archived metric may be named; a slug the value model has never defined is rejected.
Period bucket size. Buckets align to UTC hours, calendar days, ISO weeks (Monday start), calendar months or calendar quarters; the first and last bucket’s published bounds are clipped to the requested window. The window cannot hold more than 400 buckets.
Response
Currency for every monetary field here, resolved as GET /delivered-value resolves it.
Buckets ordered by period, then by group key. Every period in the window appears, and every group appears in every period, so a chart never has to fill gaps itself. For valueMetric grouping the groups are the model’s metrics, plus any archived metric that delivered value in the window. For dimension grouping the groups are the payload values observed in the window, so a window that delivered nothing has no rows. A row is one period of one group; a request producing more than 5000 rows is rejected rather than answered in part.
The signal-payload key the buckets are grouped by, echoed from the query. Present only when groupBy is dimension.