Get Sleep Log List

This endpoint returns a list of a user's sleep log entries before or after a given date, and specifying offset, limit and sort order. The data returned for different dates can include sleep periods that began on the previous date. For example, a sleep log entry for 2018-10-21 may have ended that day but started the previous night on 2018-10-20.

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

Scope: sleep

Request

• URL
• CURL

Response

• Description
• Example Response

{
  "pagination": {
    "afterDate": "2020-05-01",
    "limit": 1,
    "next": "https://api.fitbit.com/1.2/user/-/sleep/list.json?offset=1&limit=1&sort=asc&afterDate=2020-05-01",
    "offset": 0,
    "previous": "",
    "sort": "asc"
  },
  "sleep": [
    {
      "dateOfSleep": "2020-05-01",
      "duration": 20760000,
      "efficiency": 50,
      "endTime": "2020-05-01T06:20:00.000",
      "infoCode": 0,
      "isMainSleep": true,
      "levels": {
        "data": [
          {
            "dateTime": "2020-05-01T00:33:30.000",
            "level": "wake",
            "seconds": 810
          },
          {
            "dateTime": "2020-05-01T00:47:00.000",
            "level": "light",
            "seconds": 30
          },
          {
            "dateTime": "2020-05-01T00:47:30.000",
            "level": "deep",
            "seconds": 270
          },
.
.
.
          {
            "dateTime": "2020-05-01T06:04:00.000",
            "level": "deep",
            "seconds": 960
          }
        ],
        "shortData": [
          {
            "dateTime": "2020-05-01T01:05:00.000",
            "level": "wake",
            "seconds": 60
          },
          {
            "dateTime": "2020-05-01T01:41:00.000",
            "level": "wake",
            "seconds": 60
          },
.
.
.
          {
            "dateTime": "2020-05-01T06:19:30.000",
            "level": "wake",
            "seconds": 30
          }
        ],
        "summary": {
          "deep": {
            "count": 6,
            "minutes": 61,
            "thirtyDayAvgMinutes": 0
          },
          "light": {
            "count": 23,
            "minutes": 193,
            "thirtyDayAvgMinutes": 0
          },
          "rem": {
            "count": 6,
            "minutes": 41,
            "thirtyDayAvgMinutes": 0
          },
          "wake": {
            "count": 18,
            "minutes": 51,
            "thirtyDayAvgMinutes": 0
          }
        }
      },
      "logId": 36718808202,
      "logType": "auto_detected",
      "minutesAfterWakeup": 0,
      "minutesAsleep": 295,
      "minutesAwake": 51,
      "minutesToFallAsleep": 0,
      "startTime": "2020-05-01T00:33:30.000",
      "timeInBed": 346,
      "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 Range