Sahha Sleep Data Guide
This guide is designed to turn you into a confident builder of sleep-powered features using Sahha. It explains every sleep-related output we provide—what it means technically, how to interpret it scientifically (at a practical level), and how to use it inside real products without guessing.
You will learn:
- The Sahha sleep data model (how logs, biomarkers, scores, insights, and archetypes fit together)
- Every sleep biomarker and log we expose (and when you should use each)
- How the Sleep Score works, what its factors mean, and why some factors require wearables
- How to use Trends, Comparisons, and Archetypes to build trustworthy UX
Contents
- 1. The Sahha sleep data model
- 2. Data coverage: phone-only vs wearable-enhanced
- 3. Sleep Biomarkers
- 4. Sleep Data Logs
- 5. Sleep Score
- 6. Sleep Score factors
- 7. Sleep Insights: Trends & Comparisons
- 8. Sleep Archetypes
1. The Sahha sleep data model
Sahha sleep outputs come in layers. Each layer serves a different product purpose.
- Data Logs (raw streams)
- High-granularity, source-like events streamed in near real-time (typically via webhooks)
- Best for: debugging, auditing, intra-night charts, or custom analytics
- Biomarkers (clean aggregated metrics)
- Standardized, deduplicated, aggregated measures (daily or weekly)
- Best for: dashboards, goal systems, summaries, modeling
- Scores (simple outcomes + explainability)
- Normalized 0.0–1.0 outcomes with factor breakdown (value + goal + factor score)
- Best for: daily “how did I sleep?” UX and lightweight coaching
- Insights (change + context)
- Trends (weekly): “is it improving?”
- Comparisons (daily): “how does this compare to baseline/peers?”
- Archetypes (stable segmentation)
- Weekly/monthly labels summarizing patterns (e.g., schedule type, regularity type)
- Best for: personalization, notification timing, content routing
Builder rule:
- Use Biomarkers for metrics + charts.
- Use Scores for daily outcomes + explanation.
- Use Insights for narrative (“what changed” / “how does this compare”).
- Use Archetypes for stable personalization.
2. Data coverage: phone-only vs wearable-enhanced
Sahha is designed to work even when a user does not have a wearable, but the depth of sleep data depends on source capability.
Phone-only (typical coverage)
Usually supports:
- Sleep timing (start/end/mid)
- Total sleep duration
- Regularity over time (from repeated timing data)
- Sleep debt (from multi-day history)
Wearable-enhanced (richer coverage)
Often adds:
- Sleep stages (light / deep / REM)
- Awakenings and fragmentation proxies (interruptions, awake duration)
- Recovery-related factors (deep/REM driven components)
Missing data behavior (critical)
- Some biomarker fields may be absent (
null) depending on source - Some factors may be absent (
null) depending on source/history - Sleep Score requires a minimum of 3 contributing factors, otherwise the score can be
null
Product guidance:
Design a “good enough” sleep experience without wearables (duration/regularity/debt/alignment), and progressively enhance when stages/continuity become available.
3. Sleep Biomarkers
Biomarkers are the aggregated sleep metrics you’ll use most commonly in product UI and analytics. Units and periodicity matter.
Sleep biomarker catalog
| Biomarker | Unit | Periodicity | Wearable required | Meaning (builder interpretation) |
|---|---|---|---|---|
sleep_start_time | datetime | daily | No | Start of the main sleep episode |
sleep_mid_time | datetime | daily | No | Midpoint of the sleep episode (useful for circadian timing) |
sleep_end_time | datetime | daily | No | End of the main sleep episode |
sleep_duration | minute | daily | No | Minutes asleep during the episode |
sleep_debt | hour | weekly avg | No | Cumulative sleep shortfall over time (higher = more deficit) |
sleep_interruptions | count | daily | Yes | Number of awakenings/interruptions detected |
sleep_in_bed_duration | minute | daily | No | Minutes in bed (includes awake time) |
sleep_awake_duration | minute | daily | Yes | Minutes awake within the sleep window (wake after sleep onset) |
sleep_light_duration | minute | daily | Yes | Minutes estimated in light sleep |
sleep_rem_duration | minute | daily | Yes | Minutes estimated in REM sleep |
sleep_deep_duration | minute | daily | Yes | Minutes estimated in deep sleep |
sleep_regularity | index | weekly avg | No | Consistency of sleep timing over time |
sleep_latency | minute | daily | Yes | Minutes to fall asleep (if available from source) |
sleep_efficiency | percentage | daily | Yes | Sleep duration ÷ time in bed (sleep “quality per opportunity”) |
How to use biomarkers well
- For daily UX:
sleep_duration,sleep_start_time,sleep_end_time - For circadian UX:
sleep_mid_time+ schedule archetypes + circadian alignment factor - For “why did I feel bad?” UX:
sleep_awake_duration,sleep_interruptions,sleep_efficiency - For habit loops:
sleep_regularityandsleep_debt(weekly signals reduce noise)
Do not treat wearable stage minutes as clinically precise. In consumer UX, they should be framed as estimates and used directionally.
4. Sleep Data Logs
Logs represent raw-ish sleep stage streams and are best for intra-night visualization and debugging.
Sleep log catalog
| Log type | Unit | Wearable required | Meaning |
|---|---|---|---|
sleep_stage_awake | minute | Yes | Awake time within the sleep interval |
sleep_stage_deep | minute | Yes | Estimated deep sleep time |
sleep_stage_in_bed | minute | No | In-bed duration |
sleep_stage_light | minute | Yes | Estimated light sleep time |
sleep_stage_rem | minute | Yes | Estimated REM sleep time |
sleep_stage_sleeping | minute | No | Time classified as asleep |
When to use logs vs biomarkers
Use logs when you want:
- sleep-stage timeline charts
- to debug a “weird” night
- to audit sources/devices
- to compute custom per-session metrics
Use biomarkers when you want:
- dashboards
- weekly summaries
- goals and habit loops
- stable analytics and UX
5. Sleep Score
The Sleep Score is a daily composite sleep health score designed to be:
- simple (single number)
- explainable (factor breakdown)
- coverage-aware (works with or without wearables, with graceful degradation)
Scale
- API range: 0.0–1.0
- Common UI display: 0–100 (
score * 100)
States
high: 0.81–1.00 (81–100)medium: 0.66–0.80 (66–80)low: 0.51–0.65 (51–65)minimal: 0.00–0.50 (0–50)
What Sleep Score is for
Use Sleep Score as:
- the primary “sleep health today” summary
- the entry point to explanations (“why is it low?”)
- a gating signal for downstream experiences (coaching intensity, training load, productivity tips)
What Sleep Score is not for
It is not designed for:
- diagnosing sleep disorders
- clinical sleep staging conclusions
- deterministic medical inferences
6. Sleep Score factors
Factors explain why the score is what it is. Each factor is normalized (0–1) and includes a state, a raw value, and a goal.
Factor list
sleep_durationsleep_regularitysleep_continuity(wearable)sleep_debtcircadian_alignmentphysical_recovery(deep sleep; wearable)mental_recovery(REM sleep; wearable)
Factor explanations (builder-grade)
sleep_duration
What it captures: Total sleep time (quantity).
Best product use: daily summaries, “sleep opportunity” education, goal setting, habit loops.
Common pitfall: confusing “in bed” with “asleep” — use sleep_in_bed_duration + sleep_efficiency to clarify.
sleep_regularity
What it captures: Consistency of sleep timing across days/weeks.
Best product use: habit programs, schedule nudges, stable improvement loops.
Common pitfall: shift workers—avoid moralized messaging (“bad”) and use baseline framing.
sleep_continuity (wearable)
What it captures: Uninterrupted sleep / fragmentation (awakenings, awake time).
Best product use: “I slept long but feel bad” explanations, environment interventions, reduced-load recommendations.
Common pitfall: source variability—don’t infer continuity without reliable wearable data.
sleep_debt
What it captures: Multi-day accumulated deficit.
Best product use: pacing, recovery plans, “debt trending down” win-states.
Common pitfall: users expect one good night to “fix” debt—educate that debt resolves over multiple nights.
circadian_alignment
What it captures: Timing alignment between sleep schedule and circadian rhythm.
Best product use: jet lag education, light exposure advice, notification timing, schedule stabilization.
Common pitfall: treating early sleepers as “better”—alignment is personal, not moral.
physical_recovery (deep sleep; wearable)
What it captures: Estimated deep sleep contribution.
Best product use: training readiness, “recovery-mode” experiences, post-exertion guidance.
Common pitfall: deep sleep is estimated—avoid claims that imply clinical certainty.
mental_recovery (REM sleep; wearable)
What it captures: Estimated REM sleep contribution.
Best product use: cognition/emotional-regulation education, stress and sleep experiences, protecting late-night sleep.
Common pitfall: never infer mental health diagnoses from REM.
The best factor UX pattern
A trustworthy daily UI usually shows:
- Sleep Score
- The lowest 2–3 factors (non-null) as “drivers”
- Each driver shown as: value vs goal + a one-line educational explanation
That turns the score into a plan.
7. Sleep Insights: Trends & Comparisons
Insights convert raw metrics into narrative and context—key for retention and trust.
Trends (weekly)
What they do: Detect directional change over time, using a rolling multi-week window.
Best product use: weekly recap, “what changed?” storytelling, habit reinforcement, reduced-notification fatigue.
Sleep-related trend types include: Sleep Score and sleep factors (duration, regularity, continuity, debt, alignment, recovery components).
Comparisons (daily context)
What they do: Compare a metric to reference frames such as:
- global
- demographic
- baseline (user’s recent history)
Best product use: “better than usual”, “within your normal range”, “above baseline” type cards—especially baseline, which feels personalized and fair.
Design caution: Comparisons can demotivate if framed harshly. Prefer supportive language and baseline-first comparisons.
8. Sleep Archetypes
Archetypes are stable labels based on weekly/monthly behavior. They help you personalize without overreacting to a single night.
Sleep archetype catalog
| Archetype | Type | Periodicity | Wearable required | Values (exact labels) |
|---|---|---|---|---|
sleep_duration | ordinal | weekly, monthly | No | very_short_sleeper, short_sleeper, average_sleeper, long_sleeper |
sleep_efficiency | ordinal | weekly, monthly | Yes | highly_inefficient_sleeper, inefficient_sleeper, efficient_sleeper, highly_efficient_sleeper |
sleep_pattern | categorical | weekly, monthly | No | consistent_early_riser, inconsistent_early_riser, consistent_late_sleeper, inconsistent_late_sleeper, early_morning_sleeper, chronic_short_sleeper, inconsistent_short_sleeper |
sleep_quality | ordinal | weekly, monthly | No | poor_sleep_quality, fair_sleep_quality, good_sleep_quality, optimal_sleep_quality |
sleep_regularity | ordinal | weekly, monthly | No | highly_irregular_sleeper, irregular_sleeper, regular_sleeper, highly_regular_sleeper |
bed_schedule | ordinal | weekly, monthly | No | very_early_sleeper, early_sleeper, late_sleeper, very_late_sleeper |
wake_schedule | ordinal | weekly, monthly | No | very_early_riser, early_riser, late_riser, very_late_riser |
Archetypes that drive real product outcomes
- Notification timing:
bed_schedule+wake_schedule - Onboarding personalization:
sleep_pattern,sleep_regularity - Habit programs:
sleep_duration+sleep_regularity - Retention: “This week’s focus” based on archetype + trend
Builder rule: Archetypes set the default personalization; daily factors set the today message.