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 1, max 7). Only applies to application/json cursor-based pagination.
cursor	String	Query	Pagination cursor from the previous response. Only supported on application/json; returns 400 for CSV.

Response Formats

Header Value	Format
application/json	JSON (default)
text/csv	CSV

Responses

200 OK

{
  "data": [
    {
      "start_datetime": "2024-04-01T22:00:00Z",
      "end_datetime": "2024-04-02T06:00:00Z",
      "stages": [
        {
          "start_datetime": "2024-04-01T22:00:00Z",
          "end_datetime": "2024-04-01T22:30:00Z",
          "stage": "LIGHT_SLEEP"
        },
        {
          "start_datetime": "2024-04-01T22:30:00Z",
          "end_datetime": "2024-04-01T23:30:00Z",
          "stage": "DEEP_SLEEP"
        },
        {
          "start_datetime": "2024-04-01T23:30:00Z",
          "end_datetime": "2024-04-02T00:30:00Z",
          "stage": "REM_SLEEP"
        }
      ]
    }
  ],
  "next_cursor": null
}

404 Not Found

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "No Sleep for user between 2024-04-01 and 2024-04-02 found in database",
  "instance": "/v1/timeline/events/sleep/YOUR_USER_ID",
  "code": "not_found",
  "request_id": "3a7b2c1d-..."
}

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 Request (CSV)

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: text/csv" \
  -H "X-API-KEY: YOUR_API_KEY"

Sleep Stages

Stage	Description
UNSPECIFIED	Stage not determined
AWAKE	Awake during the night
LIGHT_SLEEP	Light sleep
DEEP_SLEEP	Deep / slow-wave sleep
REM_SLEEP	REM sleep

For more information

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