What sleep_debt measures
sleep_debt is the accumulated shortfall between the sleep a profile needed and the sleep it got over the last 14 nights, in hours. It is derived from stored sleep duration values, so it inherits that biomarker’s source selection and phone estimation.
| Field | sleep_debt |
|---|---|
| Unit | Hours, decimal |
| Reported | Weekly periodicity, recomputed whenever a new night’s duration lands |
| Window | The last 14 sleep days |
| Wearable required | No |
| API | GET /api/v1/profile/biomarker/{externalId}?categories=sleep&types=sleep_debt plus a date range |
| Webhook | BiomarkerCreatedIntegrationEvent. Entries update in place, upsert on id. |
Data sources
Sleep debt has no source of its own. It reads the sleep_duration biomarker for each of the last 14 sleep days, whichever source won each night. A night with no duration, from any source, is missing from the window. See how Sahha sources sleep.
How Sahha calculates sleep_debt
- Take the
sleep_durationvalue for each sleep day in the last 14, ending on the day being computed. - For each night, the shortfall is the profile’s sleep need minus the minutes asleep.
- Combine the shortfalls, with the most recent nights weighing more than older ones, and express the result in hours.
- If fewer than 2 nights have a duration, no value is written.
Absence means fewer than two nights of data, not zero debt.
Interpreting the value
Zero is the goal. Anything above it means the user has been short of their need on at least one recent night.
It is a level, not a night. Debt describes the last two weeks. A single short night raises it modestly; a run of short nights raises it a lot. Present it alongside last night’s duration so the user can tell the two apart.
It moves slowly by design. A user who starts sleeping well sees the value fall over days, not overnight, because earlier short nights remain in the window until they age out.
Related scores and insights
Score factor. Sleep debt is a factor, under the name sleep_debt, in the Sleep, Wellbeing, and Readiness scores, with unit hour and goal 0. Credit decays with debt:
| Debt (hours) | Factor score |
|---|---|
| 0 | 1.00 |
| 2 | 0.89 |
| 5 | 0.74 |
| 10 | 0.55 |
| 20 | 0.30 |
Trend. A sleep_debt trend is available on the factor score.
Comparison. None.
Archetype. sleep_quality uses debt alongside duration, regularity, and recovery.
Use cases
A recovery pacing signal. Reduce suggested training intensity or challenge difficulty while debt is elevated against the user’s recent values, and restore it as debt falls. Because the value is slow-moving, it will not flip a user’s plan day to day.
GET /api/v1/profile/biomarker/{externalId}?categories=sleep&types=sleep_debt&startDateTime=2026-08-19&endDateTime=2026-09-02An explanation card built from the nights. “You have been short of sleep on 9 of the last 14 nights” can be assembled from the same duration history and lands better than a number of hours.
A two-week program. Debt is the natural metric for a sleep reset feature because its window matches the program length and it responds to consistency rather than to one long night.
Limitations
- Phone-estimated nights count. A night estimated short because the user was on their phone late adds to the debt.
- Missing nights shrink the window silently. A user with 4 nights of data in 14 days gets a debt based on 4 nights. Check coverage before showing it.
- Absence is not zero.
Related guides
- Sleep duration for the nightly values debt is built from and how the night’s source is chosen
- Sleep regularity for the other weekly sleep signal
- Readiness Score explained for how debt feeds recovery
- Sleep Score explained for the seven sleep factors
- Data dictionary in the developer docs