What sleep_in_bed_duration measures
sleep_in_bed_duration is the number of minutes in the sleep day covered by any in-bed, asleep, stage, or awake record from the night’s source, with overlaps merged. It is the widest sleep measure and the one that every source, including the phone estimate, can supply.
| Field | sleep_in_bed_duration |
|---|---|
| Unit | Minutes |
| Reported | Daily, one value per night |
| Window | 6pm to 6pm, profile local time. Dated by the morning the window ends. |
| Wearable required | No |
| API | GET /api/v1/profile/biomarker/{externalId}?categories=sleep&types=sleep_in_bed_duration plus a date range |
| Webhook | BiomarkerCreatedIntegrationEvent. Entries update in place, upsert on id. |
Data sources
The same sources and ranking as sleep duration. What differs is which records contribute:
| Source type | In-bed time is built from |
|---|---|
| Stages plus in-bed (watches, rings) | The union of in-bed, light, deep, REM, and awake records |
| Asleep plus in-bed | The union of asleep, awake, and in-bed records |
| In-bed only, including the phone estimate | The in-bed window itself |
| Totals-only providers (WHOOP) | The provider’s in-bed total |
How Sahha calculates sleep_in_bed_duration
- Collect every in-bed, stage, asleep, and awake record from the night’s winning source that falls in the 6pm to 6pm window.
- Merge overlapping and touching records into runs, so a source that reports both a coarse in-bed period and fine stages over the same hours is counted once.
- Sum the runs. Gaps between runs, where the user was up, are not counted.
- If the source has no timestamped records but reports an in-bed total, use that.
Absence means no sleep record from any source and no qualifying phone estimate.
Interpreting the value
It is an upper bound on sleep. Duration can never exceed it. The gap between the two is the user’s awake-in-bed time.
For phone-only users it is the whole story. With no stages, in-bed and duration are equal, and this field is the honest one to show, labelled as time in bed rather than sleep.
Naps widen it. A 40-minute afternoon nap recorded by a watch adds 40 minutes here and to duration, but not to bed or wake times.
Related scores and insights
Time in bed is not a score factor and has no trend or comparison. It feeds sleep efficiency as the denominator.
Use cases
The phone-only sleep tile. Show time in bed with an “estimated” label for users whose source is the phone estimate, instead of showing sleep duration that happens to equal it.
GET /api/v1/profile/biomarker/{externalId}?categories=sleep&types=sleep_in_bed_duration&startDateTime=2026-08-26&endDateTime=2026-09-02Awake-in-bed minutes. In-bed minus duration, for wearable users, as the plain-language version of efficiency.
Limitations
- Includes naps and split sleep anywhere in the window.
- Source runs can be inflated by a Sleep schedule. An iPhone Sleep Focus schedule writes in-bed for the scheduled window whether or not the user was in bed, when no Watch is present to correct it.
- Absence is not zero.
Related guides
- Sleep duration for the asleep portion and how the night’s source is chosen
- Sleep efficiency for the ratio of the two
- Sleep latency for the gap at the start of the in-bed period
- Data dictionary in the developer docs