September 3, 2026 · 4 min read

Sleep latency

What it needs from a source, why most nights have none, how it is derived from in-bed and asleep records, and what to build.

What sleep_latency measures

sleep_latency is the number of minutes between the start of the main sleep session’s in-bed period and the first asleep record inside it: how long the user took to fall asleep.

Fieldsleep_latency
UnitMinutes
ReportedDaily, one value per night, when derivable
Window6pm to 6pm, profile local time. Dated by the morning the window ends.
Wearable requiredYes
APIGET /api/v1/profile/biomarker/{externalId}?categories=sleep&types=sleep_latency plus a date range
WebhookBiomarkerCreatedIntegrationEvent. Entries update in place, upsert on id.

Data sources

Latency is the most demanding sleep biomarker in terms of what a source must supply. From the night’s winning source, chosen as described under sleep duration, it needs:

RequirementWho meets it
A timestamped in-bed recordApple Watch with Sleep Focus, most Health Connect writers, Oura, Garmin
A timestamped asleep or stage record that starts after itAny wearable with stage detection
Both in the same sourceUsually a watch or ring. A Sleep schedule on the iPhone plus stages from a Watch are two sources, not one.

Sources that fail any line produce no latency: the phone estimate and Android’s phone detection (in-bed only), WHOOP (totals without timestamps), and any writer that starts its asleep record at the in-bed start.

How Sahha calculates sleep_latency

  1. Take the main sleep session of the night, the longest session in the 6pm to 6pm window.
  2. Within it, find the start of the in-bed record and the earliest asleep-stage record, falling back to the earliest asleep record.
  3. If both exist and the asleep start is later than the in-bed start, latency is the difference in minutes. Otherwise nothing is written.

Absence means the source could not supply it, not that the user fell asleep instantly.

Interpreting the value

It measures the device’s opinion of sleep onset. Wrist devices infer sleep from stillness and heart rate. A user reading in bed, perfectly still, can be marked asleep early. A restless user can be marked awake long after they slept.

Normal is wide. Ten to twenty minutes is typical for healthy adults [1]; under five and over thirty are both worth noticing over a week, not on one night.

Very short latency after short nights is a sleep-pressure signal. A user falling asleep in under five minutes while sleep debt is high is short on sleep, not a good sleeper.

Latency is not a score factor, has no trend, and no comparison. The nearest related factor is sleep_continuity, described under sleep interruptions, which uses awake time during the night.

Use cases

A wind-down feature with a measured outcome. Offer a pre-bed routine and report median latency over the following two weeks against the two weeks before. Latency is one of the few sleep metrics a behavioural feature can move in days.

GET /api/v1/profile/biomarker/{externalId}?categories=sleep&types=sleep_latency&startDateTime=2026-08-05&endDateTime=2026-09-02

Gate the feature on availability. Only show latency-based coaching to users with latency on at least 4 of the last 7 nights. Everyone else sees nothing rather than a blank.

Limitations

  • Most phone-only users never have it.
  • Two-source nights produce nothing. An in-bed period from one app and stages from another do not combine.
  • It follows the night’s winning source. A user with a ring and a watch gets the latency of whichever won, and the two devices disagree on sleep onset by design.
  • Absence is not zero.

References

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

Related