Documentation Index
Fetch the complete documentation index at: https://docs.tell.rs/llms.txt
Use this file to discover all available pages before exploring further.
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"
}'
{
"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
}
}
- 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 |
Periods
The periods parameter controls how many subsequent time periods to track. Default is 8, maximum is 52.
{
"granularity": "monthly",
"periods": 12,
"range": "365d"
}
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"
}'
| 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
