Get Sleep Log by Date Range

This endpoint returns a list of a user's sleep log entries for a date range. The data returned for either date can include a sleep period that ended that date but began on the previous date. For example, if you request a sleep log between 2021-12-22 and 2021-12-26, it may return log entries that span 2021-12-21 and 2021-12-22, as well as 2021-12-25 and 2021-12-26.

It uses units that correspond to the Accept-Language header provided.

Scope: sleep

Request

• URL
• CURL

Response

• Description
• Example Response

{
  "sleep": [
    {
      "dateOfSleep": "2020-01-27",
      "duration": 4560000,
      "efficiency": 86,
      "endTime": "2020-01-27T00:17:30.000",
      "infoCode": 2,
      "isMainSleep": true,
      "levels": {
        "data": [
          {
            "dateTime": "2020-01-26T23:01:00.000",
            "level": "restless",
            "seconds": 360
          },
          {
            "dateTime": "2020-01-26T23:07:00.000",
            "level": "asleep",
            "seconds": 1800
          },
.
.
.          {
            "dateTime": "2020-01-27T00:00:00.000",
            "level": "asleep",
            "seconds": 1020
          }
        ],
        "summary": {
          "asleep": {
            "count": 3,
            "minutes": 65
          },
          "awake": {
            "count": 0,
            "minutes": 0
          },
          "restless": {
            "count": 4,
            "minutes": 11
          }
        }
      },
      "logId": 25647389515,
      "minutesAfterWakeup": 0,
      "minutesAsleep": 65,
      "minutesAwake": 11,
      "minutesToFallAsleep": 0,
      "logType": "auto_detected",
      "startTime": "2020-01-26T23:01:00.000",
      "timeInBed": 76,
      "type": "classic"
    },
    {
      "dateOfSleep": "2020-01-26",
      "duration": 18000000,
      "efficiency": 94,
      "endTime": "2020-01-26T08:03:00.000",
      "infoCode": 0,
      "isMainSleep": true,
      "levels": {
        "data": [
          {
            "dateTime": "2020-01-26T03:02:30.000",
            "level": "wake",
            "seconds": 450
          },
          {
            "dateTime": "2020-01-26T03:10:00.000",
            "level": "light",
            "seconds": 330
          },
          {
            "dateTime": "2020-01-26T03:15:30.000",
            "level": "deep",
            "seconds": 450
          },
.
.
.          {
            "dateTime": "2020-01-26T07:50:00.000",
            "level": "wake",
            "seconds": 780
          }
        ],
        "shortData": [
          {
            "dateTime": "2020-01-26T03:12:00.000",
            "level": "wake",
            "seconds": 30
          },
          {
            "dateTime": "2020-01-26T03:22:30.000",
            "level": "wake",
            "seconds": 30
          },
.
.
.          {
            "dateTime": "2020-01-26T07:38:30.000",
            "level": "wake",
            "seconds": 30
          },
          {
            "dateTime": "2020-01-26T07:44:00.000",
            "level": "wake",
            "seconds": 30
          }
        ],
        "summary": {
          "deep": {
            "count": 4,
            "minutes": 46,
            "thirtyDayAvgMinutes": 0
          },
          "light": {
            "count": 19,
            "minutes": 133,
            "thirtyDayAvgMinutes": 0
          },
          "rem": {
            "count": 8,
            "minutes": 81,
            "thirtyDayAvgMinutes": 0
          },
          "wake": {
            "count": 21,
            "minutes": 40,
            "thirtyDayAvgMinutes": 0
          }
        }
      },
      "logId": 25647389514,
      "minutesAfterWakeup": 3,
      "minutesAsleep": 260,
      "minutesAwake": 40,
      "minutesToFallAsleep": 0,
      "logType": "auto_detected",
      "startTime": "2020-01-26T03:02:30.000",
      "timeInBed": 300,
      "type": "stages"
    }
  ]
}
      

Note: The rate limit headers are approximate and asynchronously updated. This means that there may be a minor delay in the decrementing of remaining requests. This could result in your application receiving an unexpected 429 response if you don't track the total number of requests you make yourself.

Note: For a complete list of response codes, please refer to the Troubleshooting Guide.

Additional Information

Types of sleep logs

This endpoint supports two kinds of sleep log types:

1. stages : Levels data is returned with 30-second granularity. 'Sleep Stages' levels include deep, light, rem, and wake.
2. classic : Levels data returned with 60-second granularity. 'Sleep Pattern' levels include asleep, restless, and awake.

Note: shortData is only included for stages sleep logs and includes wake periods that are 3 minutes or less in duration. This distinction is to simplify graphically distinguishing short wakes from longer wakes, but they are physiologically equivalent.

For information on how to interpret the sleep data, see Interpreting the Sleep Stage and Short Data.

Device generated sleep logs

The dateOfSleep in the GET sleep log endpoint response is the date on which the sleep event ends. This means that requesting a sleep log for a given date, for example 2021-12-22, may return a log entry that began the previous night on 2021-12-21. This is to account for the fact that sleep periods typically take place overnight between two dates and the dateOfSleep refers to the date the user woke up.

If the wake time during the main sleep is greater than 1 hour, the sleep log will be split into 2 logs.

Although, if the device syncs during the wake time and consistent steps and hand movement occur for at least 15 minutes, then a sleep log might be generated for the first part of the sleep. The second part of the sleep will be detected when the device syncs in the morning. If the time between the 2 sleep logs is less than 1 hour, the 2 sleep logs will be stitched together.

Manually created sleep logs

A manual sleep log is either a sleep log that has human input through the mobile or web application, or a 3rd party application records sleep using the Create Sleep Log endpoint. When a sleep log is manually recorded, a "classic" sleep log is generated. Sleep "stage" logs use the device heart rate and movement to calculate sleep stage data. When manually entering a sleep log, this information is typically not available.

It is NOT possible to create overlapping logs.

"logType" values

This field returns information on whether the user’s sleep data was automatically or manually detected. It includes the following 2 values:

1. auto_detected: Sleep was automatically detected by our sleep detection service.
2. manual: Sleep was logged by the user or edited by the user after being automatically detected.

Meta response

If the user has only 1 sleep log that is being processed, the response will contain only the meta field.

{
    "meta": {
        "retryDuration": 3000,
        "state": "pending"
    }
}

However, if there is a second sleep log present for that day, then the sleep, summary and meta fields will be returned.

{
    "meta": {
        "retryDuration": 3000,
        "state": "pending"
    }
    "sleep": [
        {{ existing sleep details }}
    ],
      "summary": {
    "stages": {
      "deep": 104,
      "light": 205,
      "rem": 75,
      "wake": 78
    },

    "summary": {
        stages: {
            "deep": 55,
            "light": 176,
            "rem": 65,
            "wake": 21
        }
        "totalMinutesAsleep": 296,
        "totalSleep Records": 2,
        "totalTimeInBed": 317
    }
}

Get Sleep Log by Date

Get Sleep Log List