Sleep

The Sleep endpoint provides access to user sleep data, including start and end times and detected sleep stages.

GET /v1/timeline/events/sleep/{user_id}

Parameters

Name	Type	In	Description
user_id	UUID	Path	The unique identifier for the user.
start_date	Date	Query	The start date for the query period (format: YYYY-MM-DD).
end_date	Date	Query	The end date for the query period (format: YYYY-MM-DD).
days	Integer	Query	Days per page (default 7, max 30). Only applies to application/json cursor-based pagination.
cursor	String	Query	Pagination cursor from the previous response.

Response Formats

Header Value	Format
application/json	JSON (default)

Response Status Codes

200 ok

The request was successful. A date range with no data returns 200 with an empty data array.

400 bad request

An invalid cursor was supplied.

See Errors for authentication, validation, and rate-limit responses.

Example Request (JSON)

cURL

curl -X GET "https://research-api.nowatch.com/v1/timeline/events/sleep/YOUR_USER_ID?start_date=2024-04-01&end_date=2024-04-02" \
  -H "accept: application/json" \
  -H "X-API-KEY: YOUR_API_KEY"

Example Response

200 OK

{
  "data": [
    {
      "start_datetime": "2024-04-01T22:00:00.000Z",
      "end_datetime": "2024-04-02T06:00:00.000Z",
      "stages": [
        {
          "start_datetime": "2024-04-01T22:00:00.000Z",
          "end_datetime": "2024-04-01T22:30:00.000Z",
          "stage": "LIGHT"
        },
        {
          "start_datetime": "2024-04-01T22:30:00.000Z",
          "end_datetime": "2024-04-01T23:30:00.000Z",
          "stage": "DEEP"
        },
        {
          "start_datetime": "2024-04-01T23:30:00.000Z",
          "end_datetime": "2024-04-02T00:30:00.000Z",
          "stage": "REM"
        }
      ]
    }
  ],
  "next_cursor": null
}

Sleep Stages

Stage	Description
AWAKE	Awake during the night (also used for manually logged awakenings)
LIGHT	Light sleep
DEEP	Deep / slow-wave sleep
REM	REM sleep
UNSPECIFIED	Stage could not be determined (e.g. poor signal or missing data)

For more information

See the Overview Screen Guide for details on how sleep data is presented in the app.