Skip to main content
GET
Get Sleep Totals

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Headers

X-Open-Wearables-API-Key
string | null

Path Parameters

user_id
string<uuid>
required

Query Parameters

start_date
string<date-time>
required

ISO 8601 datetime (e.g. 2023-11-07T05:31:56Z) or Unix timestamp in seconds. Date-only strings (e.g. 2023-11-07) are also accepted and cover the whole day, so a date-only range includes both boundary days.

Examples:

"2023-11-07T05:31:56Z"

"2023-11-07"

end_date
string<date-time>
required

ISO 8601 datetime (e.g. 2023-11-07T05:31:56Z) or Unix timestamp in seconds. Date-only strings (e.g. 2023-11-07) are also accepted and cover the whole day, so a date-only range includes both boundary days.

Examples:

"2023-11-07T05:31:56Z"

"2023-11-07"

provider
enum<string> | null

Supported data providers.

Available options:
apple,
samsung,
garmin,
health_connect,
google_health,
polar,
suunto,
whoop,
strava,
oura,
fitbit,
ultrahuman,
sensorbio,
withings,
unknown,
internal
source
string | null
device_model
string | null
data_source_id
string<uuid> | null
is_nap
boolean | null

When true, return only naps; when false, only main sleep. Omit to return both.

source_selection
enum<string> | null

all returns every source's sessions. per_session drops a session when the sessions of one source ranked higher by provider, then device type priority, cover at least SESSION_DUPLICATE_OVERLAP of it (default 0.5); sessions nothing better covers stay, and equally ranked sources never hide each other. Source filters narrow which sessions compete. Defaults to all.

Available options:
all,
per_session
filter_by_priority
boolean
default:false
deprecated

Same as source_selection=per_session.

Response

Successful Response

Sleep sessions matching a filter, added up in the database rather than paged.

count
integer
required

Sessions that match the filters, naps included

Example:

30

naps
integer
required

Of those, how many are naps

Example:

4

sleep_duration_seconds
integer
required

Sum of time asleep

Example:

799200

time_in_bed_seconds
integer
required

Sum of time in bed, or of the session's span where none was reported

Example:

871200

avg_efficiency_percent
number | null

Mean efficiency over the sessions that report one

Example:

91.4