> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beaconrevenue.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Usage intelligence — are customers using what they pay for?
> How Usage intelligence reads each customer's use of your product, what it produces today, what you see on its page, what it needs, which modules depend on it, and what it does not calculate yet.
**Usage intelligence** answers one question: *Are customers actually using what they pay for — and which way is it going?* Every morning it reads how each customer used your product, from your product analytics, and lines each one up with the customers in its own group: how many days they used it, how many people, when they last used it, and whether use is rising or falling. It belongs to the Customer family — see [Modules](/modules/overview).
This page describes the module as it runs today. Each customer's usage facts — active days, events, active users, session length, last use and the change over the last two weeks — are live. **Usage health — the score from 0 to 100 for each customer — and everything built on it: its tiers, the usage patterns, revenue in healthy usage, customers on track at month 6, and the alerts, is designed and not calculated yet.** Your usage data does not yet carry three of the five things the score is built from, and how each part turns into a score is not yet written down. [Usage intelligence — how it is calculated](/definitions/usage-intelligence) sets out every rule the live figures follow.
## What it does
A customer can pay every month and barely use what it bought. That usually shows in its use of your product weeks before it shows in billing. Usage intelligence is built to score how well each customer uses your product against customers like it, to name the shape its use is taking, and to flag a stalled start, falling use or a new team early.
Today it does the part that needs no score. Once a day, after your product analytics has loaded, it:
* **Lists every customer that sends usage** — a customer in your billing whose account in your product analytics is matched to it — and says how many of your customers that is.
* **Reads last full month's use** for each one: how many events, on how many days, by how many people, and the typical session length.
* **Notes the last day** each customer used the product.
* **Compares the last two weeks with the two before**: use rising, about the same, falling, or none in four weeks — and how many customers' use halved.
* **Groups the customers** — all of them, each size group and each segment — with the middle number of active days in each group, how many customers sit in each band of active days, and their monthly revenue from your billing.
Beacon reads your product analytics and your billing. It never writes into either, and it never contacts a customer.
## What it produces
Its headline is four figures. None is calculated yet.
| KPI | What it measures | Today |
| - | - | - |
| **Usage health** | How well each customer uses your product, from 0 to 100, against customers in its own segment — with its tier: Strong, Adequate, Concerning or Critical | Not calculated yet — three of its five parts are not in your usage data, and how each part becomes a score is not written down |
| **Revenue in healthy usage, by segment** | Monthly revenue from customers in each usage health tier, segment by segment — the figure the page leads with | Not calculated yet — waits for usage health |
| **Customers on track at month 6** | The share of customers that, by their sixth month, have reached at least the milestones usual for their segment — the earliest single sign of a customer that will do well | Not calculated yet — waits for your milestones, picked in Setup |
| [**Usage pattern**](/definitions/usage-pattern) | Which of eight shapes each customer's use has taken over the last six months — such as *strong start, then builds* or *stalled onboarding* | Not calculated yet — needs six months of usage history, and how a shape is matched to a pattern is not written down |
Usage pattern links to its definition, which also says how the [Data API](/api-reference) and [MCP](/mcp-tools) will carry it — neither serves it yet. The other three get their definitions when they are calculated.
Behind them it also produces:
| What | What it tells you | Today |
| - | - | - |
| **Customers sending usage** | How many of your customers send usage Beacon can match, out of all the customers Beacon holds for you | Produced daily |
| **Last full month's use** | For each customer: events, active days, active users and typical session length, as your product analytics records them | Produced daily |
| **Last use** | The last day each customer used the product, and the last day your usage data reaches | Produced daily |
| **The last two weeks** | Each customer's events over the last two weeks against the two before: rising if up 10% or more, falling if down 10% or more, about the same in between — and how many customers' use halved | Produced daily |
| **Active days** | The middle number of active days last month in each group, the fewest and the most, and how many customers used it on under 10 days, 10 to 19, 20 to 25, and 26 or more | Produced daily |
| **Monthly revenue of customers sending usage** | Last full month's recurring revenue from your billing, for each customer and each group | Produced daily |
| **Customers in their first year** | How many customers sending usage are in their first 12 months | Produced daily |
| **The five parts of usage health** | Milestones, features, intensity, teams and recency, each from 0 to 100 | Not calculated yet |
| **Usage health tiers** and **usage patterns** | Each customer's tier and shape | Not calculated yet |
| **Month against the month before** | Customers whose events fell by half or more against the month before | Waits for two full months of usage |
| **Alerts** | Six rules — onboarding stalled, milestones behind, usage falling, expansion ready while usage is weak, a new team started, and usage health Critical | Built, none sent |
The change over two weeks is shown on the page only. It is not a published value: what Beacon publishes about a customer's direction of use is its [usage pattern](/definitions/usage-pattern).
## How usage health will be worked out
**The figures produced today** are counts and sums of what your product analytics and billing record, worked out by fixed, written rules — the same data always gives the same figures. The full rules are in [Usage intelligence — how it is calculated](/definitions/usage-intelligence).
**Usage health — designed, not calculated.** Each customer is scored on five parts, each from 0 to 100 against customers in the same segment, then weighted and added up. Against its own segment means the same number reads the same everywhere: eight milestones by month 3 can be behind for an Enterprise customer and on track for a small one.
| Part | Weight | What it will measure | In your usage data today |
| - | - | - | - |
| **Activation milestones** | 30% | How many of the milestones usual for its segment the customer has reached, how fast and in what order, and how soon it got first value | Not yet — Setup asks which events count |
| **Feature adoption** | 25% | How many of the features customers in its segment use when they use the product fully | Not yet — your events are not matched to features |
| **Usage intensity** | 20% | Events per active user, active users per paid seat, sessions, and the direction over 30 days | Partly — events, active users, active days and session length; paid seats are not read |
| **Teams using it** | 15% | How many teams inside the customer use it, and whether they work in it together | Not yet — your usage data has no teams inside a customer |
| **Recency** | 10% | How recently and how regularly the customer used it — the earliest warning, 30 to 60 days before use thins out | Yes — the last day each customer used it |
**Tiers.** *Strong* — 80 and over. *Adequate* — 55 to 79. *Concerning* — 30 to 54. *Critical* — under 30, passed to Churn risk and Cost to serve. The Critical line at 30 is the same in every growth plan. The Concerning line moves with your growth plan:
| Growth plan | Concerning below | Critical below |
| - | - | - |
| Protect cash | 60 | 30 |
| Disciplined growth | 55 | 30 |
| Balanced growth | 55 | 30 |
| Aggressive growth | 50 | 30 |
| Land grab | 45 | 30 |
**Usage patterns.** Each customer's use over the last six months is matched to one of eight shapes: *strong start, then builds* · *spreading to more teams* · *fast start, then flat* · *slow and steady* · *late bloomer* · *one heavy team* · *peaked, then falling* · *stalled onboarding*. A new pattern is called only after it has held for 14 days. Under 60% sure, the customer reads *No clear pattern yet* and goes to its owner. The eight are fixed. See [Usage pattern](/definitions/usage-pattern) for each shape and the pairs that are easy to confuse.
**Usual milestones per segment** — the starting values, replaced with your own once 50 customers per segment have finished their first year:
| Segment size | Usual milestones | Fully started by |
| - | - | - |
| Enterprise | 12–15 | Months 4–6 |
| Mid-market | 8–10 | Months 2–4 |
| Small business | 5–7 | Months 1–3 |
**The rules.**
* **When a customer is scored** — after 7 days of usage, once its record passes Data integrity. The first months carry an early label; the score settles from month 3.
* **Onboarding stalled** — milestones under 40 once a customer reaches month 4. This line is fixed: loosening it needs the VP of Customer Success, the Head of Product and Beacon.
* **Changing the weights** — at the quarterly review, a change of up to 10% to one part applies by itself; more needs the VP of Customer Success, the Head of Product and Beacon. Milestones stay between 25% and 40%, no part reaches 40%, and the five add up to 100%. One change a quarter.
* **No decisions here** — Usage intelligence flags; it never acts on a customer. Churn risk, Expansion readiness, Cost to serve and Lifecycle economics use its readings and apply their own rules.
None of this is calculated today, because three of the five parts have nothing to read yet — milestones and features have to be picked from your events, and teams need a team property in your usage data — paid seats are not read, how each part turns what Beacon reads into a score from 0 to 100 is not yet written down, and patterns need six months of history. Until then, the page shows your real usage and says **Not yet calculated** for the score.
## What you see on its page
In Beacon, open **Customers** under Growth and choose **Usage intelligence**, under *Keep & grow*. The banner shows, for each size group, how many customers send usage and their middle number of active days last month; how many of your customers send usage and their monthly revenue; that 2 of the 5 parts of usage health can be read; and how many setup answers scoring still waits for. The page has six tabs:
* **Overview** — what your usage data shows today for each of the five parts; customers sending usage, active days last month and the last two weeks; the six checks of customers to act on and what each waits for; the eight patterns; how usage health is built; and what the module reads, feeds and where it shows up.
* **Dashboard** — the module's five charts — usage health by tier month by month, usage health by segment, patterns by segment, stalled onboardings against the usual rate, and new teams starting — each saying what it waits for; then two charts from your real usage: activity over the last two weeks by segment, and active days last month by segment.
* **Signals & alerts** — what the module watches, its six alert rules and what each waits for, and that none is sending.
* **Scorecard** — the five parts and their weights, the tiers, how your growth plan moves the Concerning line, the eight patterns, the usual milestones per segment, and the rules.
* **Customers** — every customer sending usage, filterable by size, industry and the last two weeks, with its segment, active days and active users last month, the change over two weeks and monthly revenue. Usage health and pattern read *Not yet calculated*. Select a customer for what its usage data shows and what each part can read.
* **Setup** — the module's six questions, how your usage connection is matched, and the two company questions it uses. Four answers are saved from this tab.
The page reads **Not measured yet** until your product analytics is connected, **Coming** until the first morning run has written, and **Running with gaps** once it has. It does not read **Live** yet, because usage health is not calculated.
## What it needs
| Tool | | What it adds | Checked today |
| - | - | - | - |
| **Product analytics** (PostHog) | Needed to start | Each customer's events, active days, active users and session length, by day and by month | Yes |
| **Billing** (Stripe) | Must be connected | Beacon runs no module without billing. Here it also gives each customer's start date and monthly revenue, and is what your product analytics accounts are matched to | Yes |
| **CRM** (HubSpot) | Adds detail | Each customer's size group and industry, used to group them | Used where your customer records hold them |
| **Milestones, features and teams in your usage data** | Add three of the five parts | Which events are milestones, which are features, and a team or workspace property on your events | Not yet — Setup asks |
| **Seats** | Adds to the intensity part | How many seats each customer pays for, to compare with its active users | Not read yet |
When you connect PostHog, you confirm which PostHog group is your customer and which field it shares with Stripe. That is how each PostHog account is matched to a customer. See [Connect your tools](/connect-your-tools) for how each connection is made.
## Reads from
| Module | What Usage intelligence uses it for |
| - | - |
| [**Data model**](/modules/data-model) | Your customers, their subscriptions and their usage rows, joined into one record each — read today |
| [**Segments**](/modules/segments) | Each customer is compared with its own segment. Today the page groups by a customer's confirmed segment, or by its size group and industry until segments are confirmed |
| [**Customer matching**](/modules/customer-matching) | Which customer each product analytics account belongs to. Today that is the shared field you confirm when connecting PostHog |
| [**Data integrity**](/modules/data-integrity) | A customer is scored only once its record passes the integrity check — not read yet |
| [**Segment revenue paths**](/modules/segment-revenue-paths) | The usual usage curve for each segment over the first 24 months, until your own history builds up — not read yet |
| [**Customer fit**](/modules/customer-fit) | How well the product fits a customer sets the starting expectation at signing — not read yet |
| [**Signals**](/modules/signals) | Early engagement readings from your other tools, to cross-check usage in a customer's first months — not read yet |
| [**Contract intelligence**](/modules/contract-intelligence) | The seats, products and plan each customer bought — what full use is measured against — not read yet |
| [**Deal health**](/modules/deal-health) | Who was involved on the deal at signing — the starting point for how many teams should use it — not read yet |
| [**Churn risk**](/modules/churn-risk) · **Expansion readiness** · **Cost to serve** | Cross-checks: when one of them disagrees strongly with usage, both are flagged for review — not read yet |
## Which modules read it
| Module | What it uses Usage intelligence for |
| - | - |
| [**Churn risk**](/modules/churn-risk) | Usage health is 30% of each customer's churn risk. Today it reads each customer's use over the last two weeks for its page |
| **Expansion readiness** | Usage health and the number of teams are 35% of expansion readiness |
| **Customer lifecycle** | Reaching the activation milestones moves a customer from Onboarding to Activation |
| **Cost to serve** | Each customer's change in use over the last two weeks — read today. Later, usage health: low use with high support time means friction, not growth |
| **Customer value** | Each customer's change in use over the last two weeks — read today. Later, usage health and pattern, one of the main parts of each customer's value |
| [**Forecast confidence**](/modules/forecast-confidence) | How many customers send usage, and how many saw their use fall or halve over the last two weeks — read today |
| [**Signals**](/modules/signals) · [**Customer fit**](/modules/customer-fit) · [**Segments**](/modules/segments) · [**Segment revenue paths**](/modules/segment-revenue-paths) | How usage turned out for customers that left or renewed, which kinds of customers adopt fastest, and the usual usage and patterns per segment |
| **Lifecycle economics** · **Pricing and packaging** · **Usage revenue forecast** | Usage as an early sign of lifetime value, which features each segment uses, and usage trends for revenue that moves with use — later |
Cost to serve, Customer value and Forecast confidence read the live usage facts today, and the Churn risk page shows the change over two weeks. Everything else reads usage health, its parts or its pattern, which are not calculated, so it receives nothing from this module yet. The **Modules** page in The Brain shows which modules are running for you.
## Alerts
Six alert rules are built.
| Alert | When it fires | Goes to |
| - | - | - |
| **Onboarding stalled** | At month 4, the customer has under 40 for milestones and the stalled pattern has held for 14 days. Urgent | VP of Customer Success and the customer success owner — HubSpot and Slack |
| **Milestones behind** | In a customer's first four months, milestones stay under 50 for 7 days. Becomes urgent at month 4 if it is turning into a stall | Customer success owner — HubSpot |
| **Usage falling** | Usage health falls 15 points or more in 30 days, recency drops under 50, the pattern turns to *peaked, then falling* for 14 days, or events fall by half against the month before. Urgent | Customer success owner — HubSpot and Slack |
| **Expansion ready, usage weak** | Expansion readiness says Ready (70 or more) while usage health is under 55. Automatic expansion steps pause while it is reviewed. Urgent | VP of Customer Success and the account executive — HubSpot and Slack |
| **A new team started** | A new team inside a customer uses it 5 times in 30 days for the first time, and the teams part rises 15 points for 14 days | Customer success owner and account executive — HubSpot |
| **Usage health Critical** | A customer's usage health falls under 30. Urgent | VP of Customer Success and Finance — HubSpot and Slack |
**No alert is sent yet.** Two wait for your milestones, one for teams in your usage data, one for the score, one for the score and Expansion readiness, and *Usage falling* waits for the score — its check against the month before needs two full months of usage. A separate signal for a customer whose use has stopped is being added to [Signals](/modules/signals). Who gets the alerts is picked from your Beacon users in Setup. Usage intelligence never contacts a customer or changes anything in your tools.
## Setup questions
* **Which events mark a new customer's milestones?** The most important setup decision for this module — best answered with your Head of Product. Recommended: start from Beacon's list for your kind of product. Other answers: pick events from your PostHog; later, scoring without milestones for now.
* **Which features count as using the product fully?** Recommended: pick the features from your PostHog events. Other answers: start from the events your customers use most; later.
* **How can Beacon tell teams apart inside a customer?** Recommended: a team or workspace property on your PostHog events. Other answers: departments on contacts in HubSpot; you sell to one team per customer.
* **Where is the number of seats each customer pays for?** Recommended: seat quantity on your Stripe subscriptions. Other answers: on the contract, uploaded; you don't sell by seat.
* **How long should a usage pattern hold before Beacon calls it?** 14 days. Fixed in Beacon's method, shown so you know.
* **Who gets the usage alerts?** Your customer success lead and Head of Product, picked from your Beacon users. Every alert also goes to the customer's owner in HubSpot. Waits for your users.
The first four are saved from the Setup tab and used from the next morning run. Which PostHog group is your customer, and how it is matched to Stripe, is answered on the Connections page when you connect PostHog. How you segment your customers and how you handle onboarding and support are asked once, in Company DNA.
## What is not calculated yet
* **Usage health** for each customer, its **five parts** and its **tier**.
* **Revenue in healthy usage**, **customers on track at month 6** and **usage patterns** — patterns also need six months of usage history.
* **Milestones**, **features** and **teams** — not in your usage data until Setup is answered and your events carry them; **paid seats** are not read.
* **Month against the month before** — needs two full months of usage.
* **Alerts** — none is sent yet.
* **Usage pattern, active users and last active date through the Data API and MCP** — defined on the [account object](/data-model/account), not served yet.
## Related
The ten module families and which modules are available today.
Every rule the live figures follow — who counts, the last full month, the two-week windows, active days and the groups.
The eight shapes a customer's use can take, and the pairs that are easy to confuse.
The usage values Beacon publishes about each customer: usage pattern, active users and last active date.
What changed for each customer — including usage dropping.
Whether this is the right customer — usage like similar customers is part of product fit.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.