Skip to main content
Retention shows whether users stick around. Tell groups users into cohorts by when they first appeared, then tracks what percentage returns in each subsequent period. The result is a cohort matrix — rows are cohorts, columns are time periods, cells are retention rates.

​
Run a retention analysis

curl -X POST https://your-tell-server/api/v1/retention \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "granularity": "weekly",
    "periods": 8,
    "range": "90d"
  }'
Response: 
{
  "data": {
    "cohorts": [
      {
        "cohort_date": "2025-04-07",
        "cohort_size": 320,
        "retention": [1.0, 0.45, 0.32, 0.28, 0.25, 0.22, 0.20, 0.19],
        "counts": [320, 144, 102, 90, 80, 70, 64, 61]
      },
      {
        "cohort_date": "2025-04-14",
        "cohort_size": 280,
        "retention": [1.0, 0.50, 0.36, 0.30, 0.27, 0.24, 0.21],
        "counts": [280, 140, 101, 84, 76, 67, 59]
      }
    ],
    "averages": [1.0, 0.47, 0.34, 0.29, 0.26, 0.23, 0.21, 0.19],
    "granularity": "week",
    "periods": 8
  }
}
Each cohort shows:
  • cohort_date — the start of the period when these users first appeared
  • cohort_size — how many distinct users entered in this cohort
  • retention — retention rate per period (0.0 to 1.0), where period 0 is always 1.0
  • counts — absolute user counts per period
The averages array gives the mean retention rate across all cohorts for each period offset.

​
Granularity

Control how cohorts and periods are bucketed:
GranularityAliasesCohort grouping
dailydayUsers grouped by the day they first appeared
weeklyweekUsers grouped by the week they first appeared (default)
monthlymonthUsers grouped by the month they first appeared
Weekly retention is the most common starting point. Use daily for short-term analysis (onboarding flows) and monthly for long-term trends.

​
Periods

The periods parameter controls how many subsequent time periods to track. Default is 8, maximum is 52. 
{
  "granularity": "monthly",
  "periods": 12,
  "range": "365d"
}
This tracks 12 months of retention — enough to see a full year of cohort behavior.

​
Start and return events

By default, Tell counts any event as both the cohort entry and the return activity. Use start_event and return_event to be specific: 
curl -X POST https://your-tell-server/api/v1/retention \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "granularity": "weekly",
    "periods": 8,
    "start_event": "sign_up",
    "return_event": "purchase",
    "range": "90d"
  }'
This answers: “Of users who signed up each week, what percentage made a purchase in subsequent weeks?” Useful for measuring activation, not just return visits.
FieldDefaultDescription
start_eventany eventEvent that defines cohort entry
return_eventany eventEvent that counts as a return

​
Request parameters

FieldTypeDefaultDescription
granularitystringweeklyCohort bucketing: daily, weekly, monthly
periodsinteger8Number of periods to track (1–52)
start_eventstring(any event)Cohort entry event
return_eventstring(any event)Return activity event
rangestring90dTime range for the analysis

​
Reading the cohort matrix

The retention matrix is a triangle. Earlier cohorts have more columns (more time has passed), later cohorts have fewer. Here’s how to read it:
  • Row: one cohort — all users who first appeared in that period
  • Column 0: always 100% (the cohort itself)
  • Column N: percentage of the cohort that returned N periods later
  • Averages row: mean retention across all cohorts for each column
A healthy product shows retention curves that flatten — users who survive the first few periods tend to stay. If curves keep declining, you have a leaky bucket.

​
Retention on boards

Retention has a dedicated board visualization type. Add a retention block to any board to track cohort retention over time. The block uses the same parameters: granularity, periods, and optional start/return events.

​
What’s next

  • Audiences — scope retention to a specific user group
  • Funnels — measure step-by-step conversion alongside retention
  • Segments — lifecycle segments that complement retention analysis
  • Data queries API — full API reference for the retention endpoint