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

> Measure how many users come back after their first visit — cohort by cohort.

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

```bash theme={null}
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:

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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:

```bash theme={null}
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](/analytics/boards) 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](/analytics/audiences) — scope retention to a specific user group
* [Funnels](/analytics/funnels) — measure step-by-step conversion alongside retention
* [Segments](/analytics/segments) — lifecycle segments that complement retention analysis
* [Data queries API](/api/queries) — full API reference for the retention endpoint