When to use
Each view answers a different question:
Subject
The subject is the entity whose return behavior the report tracks.
These four subjects are fixed in Agent, Cortex Agents, MLflow Tracing, Google ADK and Langfuse workspaces. In User and Warehouse workspaces, the subjects come from your dataset. User and Session are the most common.
Starting and returning events
A Retention report needs two event definitions.
Each event can have several event conditions, joined with OR, and optional property filters.
Views
The Retention report has four views. Each one shows the same cohorts from a different angle.Retention
The Retention view is the classic cohort retention matrix. Each row is a cohort, grouped by the date its subjects first performed the starting event. Each column is a time period (Day 1, Day 7 and so on). Each cell shows the share of the cohort that performed the returning event in that period. An average row at the top summarizes retention across all cohorts.Retention Over Time
The Retention Over Time view transposes the matrix. Rows are time periods and columns are cohort start dates, so you can see whether retention improves or drops across successive cohorts.Usage Interval
The Usage Interval view measures how often subjects return, not whether they return. It shows the median frequency of the returning event per time period.Usage Interval Over Time
The Usage Interval Over Time view trends the median usage frequency across cohort start dates. It shows whether engagement goes up or down over time.View reference
Calculation mode
The calculation mode sets what “retained” means in each time period.
The default is Normal.
How it works
Take 100 users who signed up on Day 0. 60 returned on Day 1, and 30 returned on Day 7.Time window
The time window looks forward past the end of the selected date range, so the last cohorts have time to return. Returns in the extra period are counted, but only subjects whose starting event falls inside the date range join a cohort. This works like Extended Time in the Funnel report.
Example: with a date range of January 1 to 31 and a 14-day time window, returns through February 14 count. Only users whose starting event happened in January are cohort members.
Calculation window
The calculation window sets how time periods are measured from the starting event.Custom time brackets
Custom time brackets replace the default sequence of periods (Day 1, Day 2, Day 3 and so on) with only the periods you list, for example Day 1, Day 7, Day 14 and Day 30. Availability: Retention and Retention Over Time views only. Usage Interval views don’t support custom time brackets.Churn toggle
The churn toggle switches between retention (the share that returned) and churn (the share that didn’t return, which is 100% minus retention). Availability: Retention and Retention Over Time views only.Group By
Group By splits retention by a dimension, so you can compare retention curves across segments such as model, environment or user cohort. Group By and binning covers sort order and binning.Constraints
MCP prompt examples
A Retention prompt for the Kubit MCP server names the starting event, the returning event, the time unit (day, week or month) and the date range. Add the calculation mode when it isn’t Normal, and a breakdown when you need one. Say “rolling retention” or “unbounded retention” to change the mode, and “usage interval” to measure how often users return. “Returning on any event” is the most common pattern, since it measures whether users come back at all.“Show me retention for users who prompted the agent, returning on any event, over the last 30 days”
“Create a weekly retention report for sign up returning on tool call, broken down by model name, last 60 days”
“Show me rolling retention for users who signed up, returning on any event, with a 14-day look-forward window, last quarter”
“Show me the weekly churn rate after first prompt over the last 90 days”
“How often do retained users return? Show me a usage interval report for prompt returning on any event”
Related
- Cohorts: build segments from retention behavior, such as users retained on Day 7.
- Funnel report: measure conversion through a sequence of steps instead of return behavior.
- Significance report: test whether a retention difference between two groups is statistically significant.