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.

FlowPassword
Token URL
/api/v1/auth/login

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.

filter_by_priority
boolean
default:false

When true, keep only the highest-priority source's sessions per sleep date (provider/device priority, same ranking as summaries). Defaults to false for backwards compatibility.

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