> ## Documentation Index
> Fetch the complete documentation index at: https://retain.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Journey

> See how far each account got into your product, and which ones are at risk.

The journey shows how far into your product every account got. That answer is its **stage**.

Each stage shows how many accounts are in it and how much MRR they bring. Pick a stage to list its accounts with their churn risk (Healthy, Stable, High, Critical), the same risk you see on Customers and in alerts. Accounts still in onboarding or activation have no churn risk yet and show as **Not scored yet**.

Churned accounts, where every subscription has ended, are left out of the journey. If one subscribes again, it comes back in the stage it had.

## The stages

Every account starts as Not activated and moves toward Power. Each stage is a level of product usage.

| Stage | What it means | Default rule |
| - | - | - |
| Not activated | Signed up, hasn't felt the value yet | Where every account starts |
| Activated | Got first value | Did your activation event in the first 7 or 14 days or, after the first 14 days, reaches Basic |
| Basic | Uses the essentials | At least 1 key feature event in the last 28 days |
| Advanced | Uses it with breadth | Used at least as many distinct key features in 28 days as the median active account (minimum 2) |
| Power | Depends on the product | Meets the Advanced rule and ranks in the top 25% of active accounts by intensity |

All calculations use a rolling 28-day window. Four full weeks, so no day of the week gets to bias the result.

<Note>
  Key features are the events you mark as key features in Retain. An active
  account is one with at least 1 event in the last 28 days and a subscription
  that hasn't been canceled.
</Note>

Intensity is `active days × ln(1 + key events)` over 28 days. Active days weigh more than raw volume, so a script firing 1,000 events in one afternoon doesn't crown itself a power user.

### Moving between stages

Accounts go up the moment they meet a rule. They go down only after missing it for 7 days straight, so one quiet weekend doesn't send anyone backward.

Activation is permanent. Once an account has activated, it never drops back to Not activated.

## Stalled accounts

An account is also flagged **stalled** when it has sat in its stage longer than 75% of the accounts that have been in that stage (those who already left and those still there), with a minimum of 14 days. While there are fewer than 5 accounts to compare, the limit is 28 days. Power accounts and churned accounts are never stalled.

## How stages are defined

You don't write the rules. Retain derives them from your own data.

* **Activation event.** Retain looks at accounts that subscribed 60 or more days ago and finds the event that best separates the ones who stayed from the ones who left. It tries counts of 1, 2, 3, 5, and 10 inside the first 7 or 14 days. It needs at least 30 such accounts, and at least 10 on each side of the split.
* **Fallback.** With fewer than 30 accounts or no clear winner, activation is "1 key feature event within 14 days".
* **Basic, Advanced, Power.** Percentiles and medians across your active accounts, as shown in the table above.
* **What defines each stage.** For Advanced and Power, Retain lists up to 3 events that show up much more in that stage than in the one below it (at least 2x as often, in at least 30% of its accounts).

Each stage carries a confidence level. High means at least 30 accounts and retention at least 10 points above the previous stage. Medium means at least 15 accounts. Anything else, and every fallback, is low. Confidence is informative and never blocks a classification.

### Editing the rules

You can replace the rules for Activated, Basic, Advanced, or Power with your own, up to 3 rules per stage, all of which must be met. A manual definition is never overwritten by the daily job.

Retain keeps refreshing its stats and the events that define the stage. Only the rules stay yours. To go back, use **Reset to automatic** on that stage.

## Day one: bringing your history

A journey with no history starts empty. There are two ways to fill it, and you can use both.

### Import from PostHog

If you use PostHog, Retain can import the last 90 days of events.

<Steps>
  <Step title="Create a personal API key">
    In PostHog, open your user settings and create a personal API key. Give
    it the **Query Read** scope.
  </Step>

  <Step title="Find your Project ID">
    It's the number in your PostHog project settings.
  </Step>

  <Step title="Fill the form in Retain">
    Go to **Sources → PostHog**, then **Import the last 90 days**. Pick your
    region (US, EU, or self-hosted). For self-hosted, enter your public
    `https://` URL. Add the Project ID and the key.
  </Step>
</Steps>

The import stops at 2,000,000 events, and Retain marks it as capped when that happens. For realtime events going forward, see [Connect PostHog](/docs/guides/connect-posthog).

### Send history through the API

Without PostHog, send past events with a `timestamp`. The `/track` endpoint accepts an ISO 8601 date, so the event lands where it happened instead of today.

```bash cURL theme={"theme":"vesper"}
curl -X POST https://api.retain.so/track \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $RETAIN_WRITE_KEY" \
  -d '{
    "userId": "user_123",
    "event": "report_exported",
    "timestamp": "2026-08-14T09:30:00Z"
  }'
```

<Note>
  The `track` method of `@retain-so/sdk` doesn't take a `timestamp` yet. Use
  the HTTP endpoint above for backfills.
</Note>

After a PostHog import, Retain replays the last 90 days, so the journey shows where accounts have been and not only where they are now. History you send through `/track` shows up on the next daily run.

Without any history, the journey still works. It fills in as events arrive.

## When it updates

Journey states are recomputed once a day, at 09:30 UTC. Stages and the rules Retain derives all refresh in that run.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.