Retention

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:

Granularity	Aliases	Cohort grouping
`daily`	`day`	Users grouped by the day they first appeared
`weekly`	`week`	Users grouped by the week they first appeared (default)
`monthly`	`month`	Users 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.

Field	Default	Description
`start_event`	any event	Event that defines cohort entry
`return_event`	any event	Event that counts as a return

Request parameters

Field	Type	Default	Description
`granularity`	string	`weekly`	Cohort bucketing: `daily`, `weekly`, `monthly`
`periods`	integer	`8`	Number of periods to track (1–52)
`start_event`	string	(any event)	Cohort entry event
`return_event`	string	(any event)	Return activity event
`range`	string	`90d`	Time 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

Getting Started

Tracking

Pipeline

Analytics

Installing

Run a retention analysis

Granularity

Periods

Start and return events

Request parameters

Reading the cohort matrix

Retention on boards

What’s next

​Run a retention analysis

​Granularity

​Periods

​Start and return events

​Request parameters

​Reading the cohort matrix

​Retention on boards

​What’s next

Run a retention analysis

Granularity

Periods

Start and return events

Request parameters

Reading the cohort matrix

Retention on boards

What’s next