Skip to main content
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:
SegmentDefinition
newFirst seen within the last 7 days
returningNot new, but active in the last 7 days
dormantLast seen 8-30 days ago
churnedLast seen more than 30 days ago

​
Engagement segments

Based on total session count (from the events table):
SegmentDefinition
one_timerOnly 1 session total
casual2-4 sessions
regular5-14 sessions
power_user15+ sessions

​
Segment counts

Get the number of users in each segment: 
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: 
[
  { "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: 
# 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. 
[
  {
    "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.
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.

​
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 data to understand what they used to do.