> ## Documentation Index > Fetch the complete documentation index at: https://learn.kubit.ai/llms.txt > Use this file to discover all available pages before exploring further. # Retention report > Measure whether users come back after a starting event: views, calculation modes, time windows, churn and Group By in the Kubit Retention report. A Retention report measures whether subjects come back after a first action, and how that return behavior changes over time. This page covers the Retention report's settings in the order they appear: subject, starting and returning events, views, calculation mode, time window, calculation window, custom time brackets, the churn toggle and Group By. ## When to use | Use case | Example | | - | - | | User stickiness | What share of users who prompted the agent on Day 0 prompt again on Day 1, Day 7 and Day 30? | | Feature re-engagement | After users first use a tool call, how many use it again within the next week? | | Cohort comparison | Do power users retain better than casual users? Compare their retention curves. | | Churn identification | Switch to the churn view to see what share of each cohort drops off at each interval. | | Usage frequency | How often do retained users come back? Switch to the **Usage Interval** view. | Each view answers a different question: | Question | View | | - | - | | What share of each cohort came back in each period? | **Retention**, the classic cohort retention matrix | | Is retention getting better or worse across cohort start dates? | **Retention Over Time** | | How often do users come back? | **Usage Interval** | | Is usage frequency going up or down over time? | **Usage Interval Over Time** | ## Subject The subject is the entity whose return behavior the report tracks. | Subject | Tracks | | - | - | | **User** | Unique users who return | | **Trace** | Unique traces | | **Session** | Unique sessions | | **Span** | Unique spans | 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. | Event | What it defines | Example | | - | - | - | | **Starting event** | The first action. Subjects are grouped into cohorts by when they first performed it. | First prompt, sign up | | **Returning event** | The action that counts as a return. The report counts how many subjects in each cohort perform it in later periods. | Any event, prompted again | 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 | View | Rows | Columns | Measures | | - | - | - | - | | **Retention** | Cohort start dates | Return periods | % retained | | **Retention Over Time** | Return periods | Cohort start dates | % retained | | **Usage Interval** | Frequency buckets | Return periods | % of users | | **Usage Interval Over Time** | Frequency buckets | Cohort start dates | % of users | ## Calculation mode The calculation mode sets what "retained" means in each time period. | Mode | A subject counts as retained in a period when it | Base for the percentage | | - | - | - | | **Normal** | Performed the returning event in that period, whether or not it was active in earlier periods | The original cohort size (Day 0) | | **Rolling** | Performed the returning event in that period and was also retained in the previous period | The previous period's retained count | | **Unbounded** | Performed the returning event in that period or any later period | The original cohort size (Day 0) | 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. | Mode | Day 1 | Day 7 | | - | - | - | | **Normal** | 60% (60 of 100) | 30% (30 of 100) | | **Rolling** | 60% (60 of 100) | 50% (30 of the 60 retained on Day 1) | | **Unbounded** | 60% (returned on Day 1 or later) | 30% (returned on Day 7 or later) | ## 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](https://learn.kubit.ai/product-analytics/reports/funnel.md). | Setting | Value | | - | - | | Range | 0 to 365 | | Unit | The selected time unit (Day, Week or Month) | | Default | Not set | **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. | Window | How periods are measured | | - | - | | **Rolling 24 Hours** | Each period is exactly 24 hours, counted from the starting event's timestamp. Day 0 is the first 24 hours, Day 1 is hours 24 to 48 and so on. Periods can span two calendar dates. | | **Strict Calendar Date** | Each period follows calendar date boundaries. Day 0 can be shorter than later days when the starting event happened mid-day. | ## 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](https://learn.kubit.ai/product-analytics/reports/common/group-by-and-binning.md) covers sort order and binning. | Constraint | Value | | - | - | | Max breakdown groups | **2** | ## Constraints | Constraint | Value | | - | - | | Compare | **Not supported.** Retention doesn't support period-over-period comparison. To compare time periods, break down by [cohorts](https://learn.kubit.ai/product-analytics/reports/cohorts.md) instead. | | Max rows shown at once | **8** | ## 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](https://learn.kubit.ai/product-analytics/reports/cohorts.md): build segments from retention behavior, such as users retained on Day 7. * [Funnel report](https://learn.kubit.ai/product-analytics/reports/funnel.md): measure conversion through a sequence of steps instead of return behavior. * [Significance report](https://learn.kubit.ai/product-analytics/reports/significance.md): test whether a retention difference between two groups is statistically significant. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.