Retention

This guide covers the configuration features of Kubit's Retention report: Subject, Starting and Returning Events, Views, Calculation Modes, Time Window, Calculation Window, Group By, and display options.

When to Use Retention

A Retention report is the right tool whenever you need to measure whether users come back after an initial action — and how that return behavior changes over time.

Choosing the right view:

• Use Retention for a classic cohort retention matrix.

• Use Retention Over Time to see how retention rates trend across cohort start dates.

• Use Usage Interval to measure how frequently users return (median events per period).

• Use Usage Interval Over Time to see how usage frequency trends over time.

Subject

The Subject defines what entity is being tracked for return behavior.

Starting Event and Returning Event

A Retention report requires two event definitions:

• Starting Event — the initial action that creates a cohort (e.g., "first prompt," "sign up"). Users are grouped into cohorts based on when they first performed this event.

• Returning Event — the action that counts as a "return" (e.g., "any event," "prompted again"). The report measures how many users from each cohort perform this event in subsequent time periods.

Each event supports multiple event conditions (OR logic) and optional property filters.

Views

Retention reports support four views, each answering a different question.

Retention

The classic cohort retention matrix. Rows are cohorts (grouped by the date they first performed the starting event). Columns are time periods (Day 1, Day 7, etc.). Each cell shows the percentage 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 same retention data, but transposed — rows are time periods and columns are cohort start dates. This view makes it easy to spot whether retention is improving or degrading across successive cohorts.

Usage Interval

Instead of measuring whether users return, this view measures how often they return. Shows the median frequency of the returning event per time period.

Usage Interval Over Time

Median usage frequency trended across cohort start dates — shows whether engagement intensity is increasing or decreasing over time.

View Quick Reference

Calculation Mode

The calculation mode controls how "retained" is defined for each time period.

Example: If 100 users signed up (Day 0), 60 returned on Day 1, and 30 returned on Day 7:

• Normal: Day 1 = 60%, Day 7 = 30% (both relative to 100)

• Rolling: Day 1 = 60% (of 100), Day 7 = 50% (of 60 — only users retained on Day 1 who also returned on Day 7)

• Unbounded: Day 1 = 60% (returned on Day 1 or later), Day 7 = 30% (returned on Day 7 or later)

Time Window (Looking Forward)

The Time Window extends the analysis period beyond the selected date range, giving cohorts more time for returns to be counted. This is the same concept as Extended Time in Funnel reports.

Example: Date range is January 1–31 with a 14-day time window. Returns through February 14 are counted, but only users whose starting event occurred in January are included as cohort members.

Calculation Window

The calculation window controls how time periods are measured relative to the starting event.

Custom Time Brackets

For Retention and Retention Over Time views, you can define custom time brackets instead of using the default sequence (Day 1, Day 2, Day 3…). Specify an array of period values to analyze only the intervals you care about — for example, Day 1, Day 7, Day 14, Day 30.

Availability: Retention and Retention Over Time views only. Not available for Usage Interval views.

Churn Toggle

Toggle between retention view (percentage who returned) and churn view (percentage who did not return — i.e., 100% minus retention).

Availability: Retention and Retention Over Time views only.

Group By

Group By splits retention data by a dimension, letting you compare retention curves across segments (e.g., by model, environment, or user cohort).

See the Group By reference for details on sort order and binning options.

Constraints

Prompting Kubit Through MCP

When using Kubit through MCP, you create Retention reports by describing the starting action, what counts as a return, and how you want to measure retention. The MCP server translates your request into the appropriate retention configuration.

Effective Prompts

A good Retention prompt specifies:

1. Starting event — the action that defines the cohort (e.g., "sign up", "first prompt")

2. Returning event — what counts as coming back (e.g., "any event", "prompted again")

3. Time unit — day, week, or month intervals

4. Date range — the time window for cohort creation

5. Calculation mode (if not Normal) — rolling or unbounded

6. Breakdown (if needed) — how to segment retention curves

Examples by Complexity

Simple — basic retention:

"Show me retention for users who prompted the agent, returning on any event, over the last 30 days"

Medium — weekly with breakdown:

"Create a weekly retention report for sign up returning on tool call, broken down by model name, last 60 days"

Advanced — rolling mode with time window:

"Show me rolling retention for users who signed up, returning on any event, with a 14-day look-forward window, last quarter"

Specialized — churn and usage interval:

"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"

Tips

• "Returning on any event" is the most common pattern — it measures whether users come back at all.

• Calculation mode defaults to Normal. Say "rolling retention" or "unbounded retention" to switch.

• Say "usage interval" to measure how frequently users return instead of whether they return.

• Retention does not support Compare — use breakdown with cohorts to compare time periods instead.