as_of and computed_at.
The names, types and availability below are fixed. No read interface or MCP tool serves them yet — this page publishes the shape ahead of the doors.
Example payload
Attributes
Neither retention value is one number for a cohort. Each is a curve — one point for each month the cohort has lived — and the shape those points make is what the figure exists to show. A single number taken off a curve is a month’s reading, not the cohort’s result.
cohort_dimension publishes the axis, not the point on it. It tells you a cohort is cut on acquisition period. It does not tell you which period. The value naming the point is not published today; a reader who needs the specific month reads the cohort’s own identifier instead.
Beacon does not publish a lifetime-value-to-acquisition-cost ratio for a cohort. Both figures are per customer, so dividing one by the other looks valid. That ratio is struck for a segment as a whole, where the population is large enough to carry it, and a second one is not struck for a cohort inside a segment — two figures bearing the same name over two different populations leaves a reader unable to tell which one they are holding.
Availability
✓ available by default · ⊕ available after an opt-in that states who becomes able to see the value · — not available.
The events door is listed and not yet served. A value marked on it has a named event —
cohort.cohort_net_revenue_retention.changed fires once for each new monthly point, cohort.cohort_lifetime_value.changed at each of the two strikes — sent once per recalculation, carrying the new value, the previous value and both timestamps. Nothing sends an event today and there is nothing to subscribe to yet. as_of and computed_at have no event of their own; they travel inside every event. cohort_type and cohort_dimension never change once a cohort exists, so their events are rare by construction; whether the creation of a new cohort is itself announced is not yet decided. The two money figures are available on this door behind the opt-in, under a grant that covers their ceiling — an event carries what a money figure needs alongside it the way a read-interface response does. A CRM property cannot, which is why the note below on your CRM records says the rendering there is still being worked out.
Every value on this object is operational, the two money figures included. cohort_acquisition_cost and cohort_lifetime_value are read by your finance team as a matter of course, and their ceiling says so. What still sets them apart is how a money figure travels, not who may look at it — the paragraph below on your CRM records covers that.
What the opt-in on the two retention curves is for. Writing either curve onto your CRM records is off by default; turning it on takes an opt-in that states who becomes able to see it. Again a rule about where the value may travel, not about who may look at it.
The two money figures on your CRM records, and the part that is not yet settled. Writing either onto your CRM records is off by default; turning it on takes an opt-in that states who becomes able to see it — the same rule about where a value may travel that governs the retention curves above.
What accompanies a money figure there is not settled. Each of these is an aggregate, assembled from many parts each converted where it was recorded, so it travels with your reporting currency and the kinds of anchor its parts were pinned under — and it carries no single anchor date and no single billing currency, because it does not have one. Through the read interface and through MCP all of that travels with the figure automatically, in the same response. A CRM property holds one value. The marks above say the door is open behind an opt-in; they do not say the rendering is finished. That is being worked out and will be stated here when it is.
Nothing on this object is reduced to a band on the way into your CRM. The two retention curves land as ratios. Neither is a modelled value, so neither is banded for the reason a modelled value is.
Both money figures are stated in your single reporting currency. The revenue and spend behind them are converted where they are recorded, under the rules set out in currency; no second conversion happens when a cohort figure is struck. Neither retention curve carries a currency of its own — each is a ratio of two revenue figures.
No rounding rule is set for the two retention curves. Beacon applies none of its own and fixes no number of decimal places. A screen or an export may round for display, so where you compare two points, compare them at the precision you received them rather than the precision a screen showed you.
Enumerated values are lowercase with underscores — became_customer, acquisition_period, usage_cluster — on every door.
Freshness
A cohort passes through three states, and how much of this object is populated depends on which one it is in. It is open while it is still accumulating and its outcome window is incomplete. It is closing at 18 months, where enough of its life has happened for provisional results. It is closed at 24 months, where the window is complete and the figures are that cohort’s record. A cohort is not closed early because an answer is wanted sooner, and it is not held open to allow late additions. Once closed, nothing on this object moves again.
Membership never changes, so nothing on this object moves for the reason segment figures move. A segment figure can shift because an account crossed a boundary, with no customer doing anything differently. That cannot happen here. Everything on a cohort moves because the customers already in it did something, or because a figure behind them was restated.
Small cohorts carry weaker figures than large ones. Below 20 accounts in a segment tier, results for that tier are pooled with comparable segments and labelled as an estimate across segments, with the account count shown.
Both timestamps travel with every value. Compare against
as_of rather than the time of the request, and read computed_at when you want to know how recently Beacon looked. How current a number is covers both.