Why do the three stage durations not add up to sleep duration?

Duration is the merged span of all asleep records, which includes asleep time a source did not classify into a stage. Stages are the classified part only. On sources that classify everything, the three sum to duration; on others they sum to less.

Where is Apple's Core sleep?

In sleep_light_duration. Apple's Core stage is what other platforms call light sleep, and Sahha maps it there.

Which stages feed the scores?

Deep sleep feeds the physical_recovery factor and REM feeds the mental_recovery factor, in the Sleep, Wellbeing, and Readiness scores. Light sleep is not a factor.

Sleep stages

What the stage biomarkers measure

Biomarker	Stage	What the device is claiming
`sleep_light_duration`	Light (Apple: Core)	Lighter non-REM sleep, usually the largest share
`sleep_deep_duration`	Deep (slow-wave)	The physically restorative stage, concentrated early in the night
`sleep_rem_duration`	REM	The dreaming stage, concentrated toward morning

All three are reported daily in minutes over the 6pm to 6pm sleep day, dated by the morning it ends, and all require a wearable.

Field	`sleep_light_duration`, `sleep_rem_duration`, `sleep_deep_duration`
Unit	Minutes
Reported	Daily, one value per night, when the source classifies stages
Window	6pm to 6pm, profile local time. Dated by the morning the window ends.
Wearable required	Yes
API	`GET /api/v1/profile/biomarker/{externalId}?categories=sleep` plus one `types` parameter per field and a date range
Webhook	`BiomarkerCreatedIntegrationEvent`. Entries update in place, upsert on `id`.

Data sources

Stages come only from devices that classify sleep, from the night’s winning source as described under sleep duration. A source with stages outranks every source without them, so a user with a watch and a phone always gets the watch’s night.

Platform	Stage records	Notes
iOS, HealthKit	`sleepAnalysis` values asleepCore, asleepDeep, asleepREM	Apple Watch only. Core maps to light.
Android, Health Connect	`SleepSessionRecord` stages	Samsung Health, Fitbit, Pixel Watch, Oura, Garmin Connect, and other writers
Direct integrations	Provider-dependent	Oura and Garmin supply timestamped stages. WHOOP supplies per-stage totals for the night.
Phone estimate and phone detection	None

How Sahha calculates sleep stages

If the provider reports its own per-stage totals for the night, use them. Providers attribute a whole session to one night, so their totals are authoritative.
Otherwise sum the timestamped records for each stage across the 6pm to 6pm window.
Write each stage that has a positive value. A stage the source never reports is absent, not zero.

Because the three are summed independently while sleep duration is a merged span, the stages can sum to less than duration when a source leaves some asleep time unclassified.

Interpreting the values

Stages are the device’s estimate, not a sleep study. Against polysomnography, consumer wearables detect sleep versus wake well and individual stages only moderately [1]. Night-to-night swings of 20 to 30 minutes in deep sleep are noise on most devices. Weekly averages are the useful unit.

Typical shares. Roughly half the night is light, 15 to 25 percent deep, 20 to 25 percent REM for healthy adults, with deep falling with age [2]. Devices differ in how they split light from deep, so shares are comparable within a device only.

Deep is front-loaded, REM is back-loaded. A short night loses REM first. A late bedtime with a fixed alarm therefore shows up in sleep_rem_duration before anything else.

Score factors. Two factors in the Sleep, Wellbeing, and Readiness scores are built on stages:

Factor	Value	Goal	Credit
`physical_recovery`	Deep minutes	90	0 → 0.22, 30 → 0.61, 60 → 0.85, 90 and above → 1.00
`mental_recovery`	REM minutes	130	0 → 0.22, 45 → 0.61, 90 → 0.85, 130 → 0.98, above 130 → 1.00

Users without stage data have neither factor and are not penalised. Light sleep is not a factor.

Trends. physical_recovery and mental_recovery trends are available on the factor scores.

Comparison. None.

Use cases

A recovery readout. Deep and REM minutes against the 90 and 130 goals, as two bars, is the standard wearable-app view and maps directly to the two factors.

GET /api/v1/profile/biomarker/{externalId}?categories=sleep&types=sleep_deep_duration&types=sleep_rem_duration&types=sleep_light_duration&startDateTime=2026-08-26&endDateTime=2026-09-02

A “sleep longer, not earlier” insight. When REM is consistently low and deep is fine, the user is cutting the end of the night. That is a specific, checkable message.

Progressive enhancement. Render the stage view only when sleep_deep_duration exists for the night. Phone-only users see the duration view instead.

Limitations

Wearable only.
Stages may not sum to duration.
Provider totals and interval sums are different methods. A user who switches from an Oura ring to a WHOOP band will see stage values move for reasons unrelated to sleep.
Apple’s Core stage is light sleep. Users comparing with the Health app will look for “Core” and not find it.
Absence is not zero.

Sleep duration for the merged asleep span and how the night’s source is chosen
Sleep interruptions for the awake records that sit between stages
Readiness Score explained for how recovery factors feed readiness
Sleep Score explained for the seven sleep factors
Data dictionary in the developer docs

References

Chinoy ED, Cuellar JA, Huwa KE, et al. Performance of seven consumer sleep-tracking devices compared with polysomnography. Sleep. 2021;44(5):zsaa291. https://doi.org/10.1093/sleep/zsaa291
Ohayon MM, Carskadon MA, Guilleminault C, Vitiello MV. Meta-analysis of quantitative sleep parameters from childhood to old age in healthy individuals. Sleep. 2004;27(7):1255-1273. https://doi.org/10.1093/sleep/27.7.1255