External: Events

Get Sleep Totals

Changed on

Returns the count, naps, time asleep, time in bed and mean efficiency of the sessions.

The same filters as the sleep list, so it adds up exactly what that would page through.

Added up in the database, so it covers every matching session however many there are, without paging through them.

get/api/v1/users/{user_id}/events/sleep/totals

Request

  • Base URL: https://api.openwearables.io (the document declares no server; this is the origin it was published from)
  • URL: https://api.openwearables.io/api/v1/users/{user_id}/events/sleep/totals
  • Auth: OAuth 2 (password, token URL /api/v1/auth/login)

Path parameters

user_idstring uuid required

Query parameters

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

Example:2023-11-07T05:31:56Z
end_datestring 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.

Example:2023-11-07T05:31:56Z
provider'apple' | 'samsung' | 'garmin' | 'health_connect' | 'google_health' | 'polar' | 'suunto' | 'whoop' | 'strava' | 'oura' | 'fitbit' | 'ultrahuman' | 'sensorbio' | 'withings' | 'unknown' | 'internal'

Supported data providers.

sourcestring nullable
device_modelstring nullable
data_source_idstring uuid nullable
is_napboolean nullable

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

filter_by_priorityboolean

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.

Headers

X-Open-Wearables-API-Keystring nullable

Response

Successful Response

countinteger required

Sessions that match the filters, naps included

napsinteger required

Of those, how many are naps

sleep_duration_secondsinteger required

Sum of time asleep

time_in_bed_secondsinteger required

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

avg_efficiency_percentnumber nullable

Mean efficiency over the sessions that report one

Example response

{
  "count": 30,
  "naps": 4,
  "sleep_duration_seconds": 799200,
  "time_in_bed_seconds": 871200,
  "avg_efficiency_percent": 91.4
}

Changes