OPopenwearables
External: Events

List Sleep Sessions

Changed on

Returns sleep sessions (including naps).

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

Request

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
includeSleepInclude[]
cursorstring nullable
limitinteger
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.

source_selection'all' | 'per_session' nullable

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.

filter_by_priorityboolean

Same as source_selection=per_session.

Headers

X-Open-Wearables-API-Keystring nullable

Response

Successful Response

Example response

{
  "data": [
    {
      "source": {
        "provider": "apple",
        "source": "Connect",
        "device": "iPhone15,2",
        "device_id": "R9ZW30ABC12"
      },
      "duration_seconds": 28800,
      "sleep_duration_seconds": 25800,
      "time_in_bed_seconds": 28200,
      "is_final": true
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6IjEyMzQ1Njc4OTAiLCJ0cyI6MTcwNDA2NzIwMH0",
    "total_count": 150
  }
}

Changes

  • fd7798133dceRevision changes
    • info

      added the required property // to the response with the status

  • 6a9e85a49956Revision changes
    • breaking

      the response's property type changed from array to string for status

    • info

      media type application/json was changed to a more specific media type application/problem+json for the response status

    • info

      the response property became required for the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status