Get Sleep Log by Date Range
chevron down
 

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

GET /1.2/user/[user-id]/sleep/date/[startDate]/[endDate].json

URI Arguments
user-id required The encoded ID of the user. Use "-" (dash) for current logged-in user.
startDate required The date for the first sleep log to be returned in the format yyyy-MM-dd.
endDate required The date for the last sleep log to be returned in the format yyyy-MM-dd.

Maximum range: 100 days

Request Headers
authorization required Specify the token type and Fitbit user’s access token.
Token type: Bearer
accept optional Defines the media type of the response content the client is expecting.
Supported: application/json
accept-language optional The measurement unit system to use for response values. See Localization.
accept-locale optional The locale to use for response values. See Localization.

Examples
GET https://api.fitbit.com/1.2/user/-/sleep/date/2020-01-01/2020-01-05.json
GET https://api.fitbit.com/1.2/user/GGNJL9/sleep/date/2020-01-01/2020-01-05.json
curl -X GET "https://api.fitbit.com/1.2/user/-/sleep/date/2020-01-01/2020-01-05.json" \
-H "accept: application/json" \
-H "authorization: Bearer <access_token>"


Response

Element Name Description
sleep : dateOfSleep The date the sleep log ended.
sleep : duration Length of the sleep in milliseconds.
sleep : efficiency Calculated sleep efficiency score. This is not the sleep score available in the mobile application.
sleep : endTime Time the sleep log ended.
sleep : infoCode An integer value representing the quality of data collected within the sleep log.
  • 0 = Sufficient data to generate a sleep log.
  • 1 = Insufficient heart rate data.
  • 2 = Sleep period was too short (less than 3 hours).
  • 3 = Server-side issue.
sleep : isMainSleep Boolean value: true or false
sleep : levels : data : dateTime Timestamp the user started in sleep level.
sleep : levels : data : level The sleep level the user entered. The values returned for the sleep log type are:
classic: restless | asleep | awake
stages: deep | light | rem | wake
sleep : levels : data : seconds The length of time the user was in the sleep level. Displayed in seconds.
sleep : levels : shortData : dateTime Timestamp the user started in sleep level. Only supported when log type = stages.
sleep : levels : shortData : level The sleep level the user entered. Only supported when log type = stages.
sleep : levels : shortData : seconds The length of time the user was in the sleep level. Displayed in seconds.
sleep : levels : summary : [level] : count Total number of times the user entered the sleep level.
sleep : levels : summary : [level] : minutes Total number of minutes the user appeared in the sleep level.
sleep : levels : summary : [level] : thirtyDayAvgMinutes The average sleep stage time over the past 30 days. A sleep stage log is required to generate this value. When a classic sleep log is recorded, this value will be missing.
sleep : logId Sleep log ID.
sleep : minutesAfterWakeup The total number of minutes after the user woke up.
sleep : minutesAsleep The total number of minutes the user was asleep.
sleep : minutesAwake The total sum of "wake" minutes only. It does not include before falling asleep or after waking up.
sleep : minutesToFallAsleep The total number of minutes before the user falls asleep. This value is generally 0 for autosleep created sleep logs.
sleep : logType The type of sleep in terms of how it was logged. See "logType" for more detail.

Supported: auto_detected | manual
sleep : startTime Time the sleep log begins.
sleep : timeInBed Total number of minutes the user was in bed.
sleep : type The type of sleep log.
Supported : classic | stages
{
  "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"
    }
  ]
}
      

Response Headers
content-type The media type of the response content being sent to the client.
Supported: application/json
fitbit-rate-limit-limit The quota number of calls.
fitbit-rate-limit-remaining The number of calls remaining before hitting the rate limit.
fitbit-rate-limit-reset The number of seconds until the rate limit resets.
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.

Response Type
HTTP Status Code HTTP response code. List of codes are found in the Troubleshooting Guide.
Status Message Description of the status code.
Response Body Contains the JSON response to the API call. When errors are returned by the API call, the errorType, fieldName and message text will provide more information to the cause of the failure.

Response Codes
200 A successful request.
400 The request had bad syntax or was inherently impossible to be satisfied.
401 The request requires user authentication.
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

Some of the sleep log processing occurs asynchronously. On rare occassions, your application may be querying the sleep logs while the sleep data is still being processed. If the sleep logs are still in a processing state, a "meta" response will be returned. This response will indicate a retry duration given in milliseconds. The "meta" response may evolve with additional fields in the future; API clients should be prepared to ignore any new object properties they do not recognize.

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
    }
}