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

# Segments

> Built-in lifecycle and engagement segments with user counts and drill-down.

Tell automatically classifies your users into segments based on their behavior — no configuration needed. You get lifecycle segments (is this user new or churned?) and engagement segments (is this a power user or a one-timer?) computed at query time from your actual data.

## Built-in segments

### Lifecycle segments

Point-in-time classification based on when a user was first and last seen:

| Segment       | Definition                             |
| ------------- | -------------------------------------- |
| **new**       | First seen within the last 7 days      |
| **returning** | Not new, but active in the last 7 days |
| **dormant**   | Last seen 8-30 days ago                |
| **churned**   | Last seen more than 30 days ago        |

### Engagement segments

Based on total session count (from the events table):

| Segment         | Definition           |
| --------------- | -------------------- |
| **one\_timer**  | Only 1 session total |
| **casual**      | 2-4 sessions         |
| **regular**     | 5-14 sessions        |
| **power\_user** | 15+ sessions         |

## Segment counts

Get the number of users in each segment:

```bash theme={null}
curl "https://your-tell-server/api/v1/metrics/segments?range=30d" \
  -H "Authorization: Bearer $TOKEN"
```

Returns all 8 segments with their user counts and category:

```json theme={null}
[
  { "segment": "new", "category": "lifecycle", "users": 342 },
  { "segment": "returning", "category": "lifecycle", "users": 1205 },
  { "segment": "dormant", "category": "lifecycle", "users": 587 },
  { "segment": "churned", "category": "lifecycle", "users": 2341 },
  { "segment": "one_timer", "category": "engagement", "users": 891 },
  { "segment": "casual", "category": "engagement", "users": 645 },
  { "segment": "regular", "category": "engagement", "users": 412 },
  { "segment": "power_user", "category": "engagement", "users": 189 }
]
```

Lifecycle and engagement counts are computed independently — a user can be both "returning" and "power\_user".

## Segment drill-down

See which users belong to a specific segment:

```bash theme={null}
# List power users with their stats
curl "https://your-tell-server/api/v1/metrics/segments/power_user?range=30d&limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

For lifecycle segments, the response includes `first_seen` and `last_seen` timestamps. For engagement segments, it includes `session_count`.

```json theme={null}
[
  {
    "device_id": "abc123",
    "segment": "power_user",
    "session_count": 47
  }
]
```

## How segments are computed

Segments are calculated at query time — not pre-computed. Tell runs a single query using your filter's time range to classify users. This means segment counts always reflect the current state of your data within the selected time range.

No ML is involved in these segments. For ML-based segmentation (auto-generated clusters and churn predictions), see [Predictions](/analytics/predictions/overview).

<Note>
  Lifecycle segments are a **snapshot** — they classify all users right now using fixed 7/30-day windows. For a **time series** view of how new, returning, and resurrected users change over time, see the [lifecycle metric](/analytics/events#lifecycle).
</Note>

## Use cases

**Spotting churn early.** Check the dormant segment regularly. If it's growing faster than new users are arriving, you have a retention problem.

**Measuring engagement quality.** A healthy product has more regular and power users than one-timers. Track the ratio over time.

**Targeting re-engagement.** Drill into the dormant or churned segments to find users who were once active. Combine with the [events](/analytics/events) data to understand what they used to do.