Sleep Logs
chevron down
 

Sleep Logs

Get Sleep Logs

The Get Sleep Logs by Date endpoint returns a summary and list of a user's sleep log entries (including naps) as well as detailed sleep entry data for a given day.

This endpoint supports two kinds of sleep data:

  • stages : Levels data is returned with 30-second granularity. 'Sleep Stages' levels include deep, light, rem, and wake.

  • classic : Levels data returned with 60-second granularity. 'Sleep Pattern' levels include asleep, restless, and awake.

The response could be a mix of classic and stages sleep logs.

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.

Resource URL

GET https://api.fitbit.com/1.2/user/[user-id]/sleep/date/[date].json

URL parameters:

user-id The ID of the user. Use "-" (dash) for current logged-in user.
date The date of records to be returned. In the format yyyy-MM-dd.

Example Request

GET https://api.fitbit.com/1.2/user/-/sleep/date/2017-04-02.json

Example Response

Note: The text within the brackets <> is a descriptive placeholder for a value or repeated elements.

{
    "sleep": [
        {
            "dateOfSleep": "2017-04-02",
            "duration": <value in milliseconds>,
            "efficiency": <value>,
            "isMainSleep": true,
            "levels": {
                "summary": {
                    "deep": {
                        "count": <value>,
                        "minutes": <value>,
                        "thirtyDayAvgMinutes": <value>
                    },
                    "light": {
                        "count": <value>,
                        "minutes": <value>,
                        "thirtyDayAvgMinutes": <value>
                    },
                    "rem": {
                        "count": <value>,
                        "minutes": <value>,
                        "thirtyDayAvgMinutes": <value>
                    },
                    "wake": {
                        "count": <value>,
                        "minutes": <value>,
                        "thirtyDayAvgMinutes": <value>
                    }
                },
                "data": [
                    {
                        "datetime": "2017-04-01T23:58:30.000",
                        "level": "wake",
                        "seconds": <value>
                    },
                    {
                        "datetime": "2017-04-02T00:16:30.000",
                        "level": "rem",
                        "seconds": <value>
                    },
                    <...>
                ],
                "shortData": [
                    {
                        "datetime": "2017-04-02T05:58:30.000",
                        "level": "wake",
                        "seconds": <value>
                    },
                    <...>
                ]
            },
            "logId": <value>,
            "minutesAfterWakeup": <value>,
            "minutesAsleep": <value>,
            "minutesAwake": <value>,
            "minutesToFallAsleep": <value>, // this is generally 0 for autosleep created sleep logs
            "startTime": "2017-04-01T23:58:30.000",
            "timeInBed": <value in minutes>,
            "type": "stages"
        },
        {
            "dateOfSleep": "2017-04-02",
            "duration": <value in milliseconds>,
            "efficiency": <value>,
            "isMainSleep": false,
            "levels": {
                "data": [
                    {
                        "dateTime": "2017-04-02T12:06:00.000",
                        "level": "asleep",
                        "seconds": <value>
                    },
                    {
                        "dateTime": "2017-04-02T12:13:00.000",
                        "level": "restless",
                        "seconds": <value>
                    },
                    {
                        "dateTime": "2017-04-02T12:14:00.000",
                        "level": "awake",
                        "seconds": <value>
                    },
                    <...>
                ],
                "summary": {
                    "asleep": {
                        "count": 0, // this field should not be used for "asleep" summary info
                        "minutes": <value>
                    },
                    "awake": {
                        "count": <value>,
                        "minutes": <value>
                    },
                    "restless": {
                        "count": <value>,
                        "minutes": <value>
                    }
                }
            },
            "logId": <value>,
            "minutesAfterWakeup": <value>,
            "minutesAsleep": <value>,
            "minutesAwake": <value>,
            "minutesToFallAsleep": <value>, // this is generally 0 for autosleep created sleep logs
            "startTime": "2017-04-02T12:06:00.000",
            "timeInBed": <value in minutes>,
            "type": "classic"
        }
    ],
    "summary": {
        "totalMinutesAsleep": <value>,
        "totalSleepRecords": 2,
        "totalTimeInBed": <value in minutes>
    }
}

Note: Some processing is asynchronous. If the system is still processing one or more sleep logs that should be in the response when this API is queried, the 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.

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

Get Sleep Logs by Date Range

The Get Sleep Logs by Date Range endpoint returns a list of a user's sleep log entries (including naps) as well as detailed sleep entry data for a given date range (inclusive of start and end dates).

This endpoint supports two kinds of sleep data:

  • stages : Levels data is returned with 30-second granularity. 'Sleep Stages' levels include deep, light, rem, and wake.

  • classic : Levels data returned with 60-second granularity. 'Sleep Pattern' levels include asleep, restless, and awake.

The response could be a mix of classic and stages sleep logs.

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.

Resource URL

GET https://api.fitbit.com/1.2/user/[user-id]/sleep/date/[startDate]/[endDate].json

URL parameters:

user-id The ID of the user. Use "-" (dash) for current logged-in user.
startDate The date for the first sleep log to be returned. In the format yyyy-MM-dd. This date is inclusive
endDate The date for the end sleep log to be returned. In the format yyyy-MM-dd. This date is inclusive.

Example Request

GET https://api.fitbit.com/1.2/user/-/sleep/date/2017-04-02/2017-04-08.json

Example Response

Note: The text within the brackets <> is a descriptive placeholder for a value or repeated elements.

{
    "sleep": [
        {
            "dateOfSleep": "2017-04-02",
            "duration": <value in milliseconds>,
            "efficiency": <value>,
            "isMainSleep": <true|false>,
            "levels": {
                "summary": {
                    "deep": {
                        "count": <value>,
                        "minutes": <value>,
                        "thirtyDayAvgMinutes": <value>
                    },
                    "light": {
                        "count": <value>,
                        "minutes": <value>,
                        "thirtyDayAvgMinutes": <value>
                    },
                    "rem": {
                        "count": <value>,
                        "minutes": <value>,
                        "thirtyDayAvgMinutes": <value>
                    },
                    "wake": {
                        "count": <value>,
                        "minutes": <value>,
                        "thirtyDayAvgMinutes": <value>
                    }
                },
                "data": [
                    {
                        "datetime": "2017-04-01T23:58:30.000",
                        "level": "wake",
                        "seconds": <value>
                    },
                    {
                        "datetime": "2017-04-02T00:16:30.000",
                        "level": "light",
                        "seconds": <value>
                    },
                    <...>
                ],
                "shortData": [
                    {
                        "datetime": "2017-04-02T05:58:30.000",
                        "level": "wake",
                        "seconds": <value>
                    },
                    <...>
                ]
            },
            "logId": <value>,
            "minutesAfterWakeup": <value>,
            "minutesAsleep": <value>,
            "minutesAwake": <value>,
            "minutesToFallAsleep": <value>, // this is generally 0 for autosleep created sleep logs
            "startTime": "2017-04-01T23:58:30.000",
            "timeInBed": <value in minutes>,
            "type": "stages"
        },
        <...>
    ]
}

Note: Some processing is asynchronous. If the system is still processing one or more sleep logs that should be in the response when this API is queried, the 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.

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

Get Sleep Logs List

The Get Sleep Logs List endpoint returns a list of a user's sleep logs (including naps) before or after a given day with offset, limit, and sort order.

This endpoint supports two kinds of sleep data:

  • stages : Levels data is returned with 30-second granularity. 'Sleep Stages' levels include deep, light, rem, and wake.

  • classic : Levels data returned with 60-second granularity. 'Sleep Pattern' levels include asleep, restless, and awake.

The response could be a mix of classic and stages sleep logs.

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.

Resource URL

GET https://api.fitbit.com/1.2/user/-/sleep/list.json

URL parameters:

user-id The encoded ID of the user. Use "-" (dash) for current logged-in user.
beforeDate The date in the format yyyy-MM-ddTHH:mm:ss. Only yyyy-MM-dd is required. Either beforeDate or afterDate must be specified. Set sort to desc when using beforeDate.
afterDate The date in the format yyyy-MM-ddTHH:mm:ss. Only yyyy-MM-dd is required. Either beforeDate or afterDate must be specified. Set sort to asc when using afterDate.
sort

The sort order of entries by date. Required.

Use asc (ascending) when you want the oldest sleep log to be shown first.

Use desc (descending) when you want the latest sleep log to be shown first.

limit The max of the number of sleep logs returned. Required.
offset

This should always be set to 0. Required for now.

IMPORTANT: To paginate, request the next and previous links in the pagination response object. Do not manually specify the offset parameter, as it will be removed in the future and your app will break.

Example Request

GET https://api.fitbit.com/1.2/user/-/sleep/list.json?beforeDate=2017-03-27&sort=desc&offset=0&limit=1

Example Response

Note: The text within the brackets <> is a descriptive placeholder for a value or repeated elements.

{
    "pagination": {
        "beforeDate": "2017-03-27",
        "limit": 1,
        "next": "https://api.fitbit.com/1.2/user/-/sleep/list.json?offset=1&limit=1&sort=desc&beforeDate=2017-03-27",
        "offset": 0,
        "previous": "",
        "sort": "desc"
    },
    "sleep": [
        {
            "dateOfSleep": "2017-03-26",
            "duration": <value in milliseconds>,
            "efficiency": <value>,
            "levels": {
                "summary": {
                    "deep": {
                        "count": <value>,
                        "minutes": <value>,
                        "thirtyDayAvgMinutes": <value>
                    },
                    "light": {
                        "count": <value>,
                        "minutes": <value>,
                        "thirtyDayAvgMinutes": <value>
                    },
                    "rem": {
                        "count": <value>,
                        "minutes": <value>,
                        "thirtyDayAvgMinutes": <value>
                    },
                    "wake": {
                        "count": <value>,
                        "minutes": <value>,
                        "thirtyDayAvgMinutes": <value>
                    }
                },
                "data": [
                    {
                        "datetime": "2017-03-25T23:58:30.000",
                        "level": "wake",
                        "seconds": <value>
                    },
                    {
                        "datetime": "2017-03-26T00:16:30.000",
                        "level": "light",
                        "seconds": <value>
                    },
                    <...>
                ],
                "shortData": [
                    {
                        "datetime": "2017-03-26T05:58:30.000",
                        "level": "wake",
                        "seconds": <value>
                    },
                    <...>
                ]
            },
            "logId": <value>,
            "minutesAfterWakeup": <value>,
            "minutesAsleep": <value>,
            "minutesAwake": <value>,
            "minutesToFallAsleep": <value>, // this is generally 0 for autosleep created sleep logs
            "startTime": "2017-03-25T23:58:30.000",
            "timeInBed": <value in minutes>,
            "type": "stages"
        },
        <...>
    ]
}

Note: Some processing is asynchronous. If the system is still processing one or more sleep logs that should be in the response when this API is queried, the 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.

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

Interpreting the Sleep Stage and Short Data

When sleep data is displayed through the Web APIs, the data is represented in 2 ways:

  1. The "data" grouping displays the sleep stages and any wake periods > 3 minutes (180 seconds).
  2. The "shortData" grouping displays the short wake periods representing physiological awakenings that are <= 3 minutes (180 seconds).

The “shortData" is separated to provide better visualization when evaluating the sleep data. Even though the short wakes are not included as a wake stage within the “data” grouping, the short wakes should be considered awake. There will be some overlap between the “shortData” and the sleep stage “data”. The “shortData” will take precedence by overriding any of the sleep stages in “data”. Also, the “shortData” is allowed to span over multiple stages. As a result, the “shortData” should be added to the total wake time, and the overlapping time removed from the stage's data resulting in a bisection of the sleep stage.

For example, let's say we have the following sleep stage and short data information:

     "levels": {
        "data": [
          {
            "dateTime": "2020-01-30T01:43:30.000",
            "level": "rem",
            "seconds": 180
          },
          {
            "dateTime": "2020-01-30T01:46:30.000",
            "level": "light",
            "seconds": 60
          },
        ],
        "shortData": [
          {
            "dateTime": "2020-01-30T01:44:30.000",
            "level": "wake",
            "seconds": 60
          }
        ]

The “rem” stage lasts for 3 minutes and ends at 01:46:30.000. During the “rem” stage, there is a short wake period at 01:44:30.000 lasting for 1 minute. This short wake splits the “rem” stage into 2 separate stages of rem sleep. When calculating the summary data, these periods of shortData need to be considered. In this case, the short “wake” length and count need to be added to the sleep “wake” summary. The “rem” summary count should be increased by 1 and the “rem” seconds are subtracted by the length of the short “wake” period. When the short wake period appears at the beginning or end of a sleep stage, the sleep stage count will not increase.

In actuality, the data ends up looking like:

          {
            "dateTime": "2020-01-30T01:43:30.000",
            "level": "rem",
            "seconds": 90
          },
          {
            "dateTime": "2020-01-30T01:45:00.000",
            "level": "wake",
            "seconds": 60
          }
          {
            "dateTime": "2020-01-30T01:46:00.000",
            "level": "rem",
            "seconds": 30
          },
          {
            "dateTime": "2020-01-30T01:46:30.000",
            "level": "light",
            "seconds": 60
          }

When verifying the sleep summary totals, it might be easier to visualize by expanding the “data” into 30 second periods, then set all of the time periods specified in “shortData” to wake. This table represents the previous example in 30 second periods.

dateTime level seconds
2020-01-30T01:43:30.000 rem 30
2020-01-30T01:44:00.000 rem 30
2020-01-30T01:44:30.000 rem 30
2020-01-30T01:45:00.000 wake 30
2020-01-30T01:45:30.000 wake 30
2020-01-30T01:46:00.000 rem 30
2020-01-30T01:46:30.000 light 30
2020-01-30T01:47:00.000 light 30

As a result, the final totals for this example end up being:

rem = 120 seconds with count = 2
light = 60 seconds with count = 1
wake = 60 seconds with count = 1

To calculate the minutesAsleep and minutesInBed, consider

  • minutesAsleep = deep + light + rem
  • minutesInBed = deep + light + rem + wake

Log Sleep

The Log Sleep endpoint creates a log entry for a sleep event and returns a response in the format requested. Keep in mind that it is NOT possible to create overlapping log entries. The dateOfSleep in the response for the sleep log is the date on which the sleep event ends.

This endpoint supports two kinds of sleep data:

  • stages : Levels data is returned with 30-second granularity. 'Sleep Stages' levels include deep, light, rem, and wake.

  • 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.

Resource URL

POST https://api.fitbit.com/1.2/user/[user-id]/sleep.json
user-id The ID of the user. Use "-" (dash) for current logged-in user.

POST Parameters

startTime required Start time; hours and minutes in the format HH:mm.
duration required Duration in milliseconds.
date required Log entry date in the format yyyy-MM-dd.

Example Request

POST https://api.fitbit.com/1.2/user/-/sleep.json?date=2017-03-27&startTime=02:32&duration=7200000

Example Response

{
    "sleep": {
        "dateOfSleep": "2017-03-27",
        "duration": <value in milliseconds>,
        "efficiency": <value>,
        "isMainSleep": <true|false>,
        "levels": {
            "data": [
                {
                    "dateTime": "2017-03-27T02:32:00.000",
                    "level": "asleep",
                    "seconds": <value>
                },
                <...>
            ],
            "summary": {
                "asleep": {
                    "count": 0, // this field should not be used for "asleep" summary info
                    "minutes": <value>
                },
                "awake": {
                    "count": <value>,
                    "minutes": <value>
                },
                "restless": {
                    "count": <value>,
                    "minutes": <value>
                }
            }
        },
        "logId": <value>,
        "minutesAfterWakeup": <value>,
        "minutesAsleep": <value>,
        "minutesAwake": <value>,
        "minutesToFallAsleep": <value>, // this is generally 0 for autosleep created sleep logs
        "startTime": "2017-03-27T02:32:00.000",
        "timeInBed": <value in minutes>,
        "type": "classic"
    }
}

Delete Sleep Log

The Delete Sleep Log endpoint deletes a user's sleep log entry with the given ID.

Resource URL

DELETE https://api.fitbit.com/1/user/[user-id]/sleep/[log-id].json
user-id The encoded ID of the user. Use "-" (dash) for current logged-in user.
log-id ID of the sleep log to be deleted.

Response

A successful request will return a 204 status code with an empty response body.

Sleep Goals

Get Sleep Goal

The Get Sleep Goal endpoint returns a user's current sleep goal using unit in the unit system that corresponds to the Accept-Language header provided in the format requested.

Access Type: Read

Rate Limited: Yes

Resource URL

GET https://api.fitbit.com/<api-version>/user/-/sleep/goal.json
api-version The API version, which is currently 1.
Example
GET https://api.fitbit.com/1/user/-/sleep/goal.json

Authentication

Authentication is provided via token credentials. All authentication header parameters are required.

Request Headers

Accept-Language optional The language to use for response values. Language is used to determine the food measurement units returned.

Response

The API Response is in the requested JSON.

Response Body Format

Note: The text within the brackets <> is a descriptive placeholder for a value or repeated elements.

JSON Response

{
    "goal": {
        "minDuration":<value>,
        "updatedOn":<value>
    }
}

JSON Example

{
    "goal": {
       "minDuration":"480",
       "updatedOn":"2015-04-07T09:42:10.872"
    }
}

Update Sleep Goal

The Update Sleep Goal endpoint creates or updates a user's sleep goal and get a response in the in the format requested.

Access Type: Read & Write

Resource URL

POST https://api.fitbit.com/<api-version>/user/-/sleep/goal.json
api-version The API version, which is currently 1.
Example
POST https://api.fitbit.com/1/user/-/sleep/goal.json

POST Parameters

minDuration required The target sleep duration is in minutes.

Authentication

Authentication is provided via token credentials. All authentication header parameters are required.

Request Headers

None

Response

The API Response is in the requested JSON.

Response Body Format

Note: The text within the brackets <> is a descriptive placeholder for a value or repeated elements.

JSON Response

{
    "goal": {
        "minDuration":<value>,
        "updatedOn":<value>
    }
}

JSON Example

{
    "goal": {
        "minDuration":540,
        "updatedOn":"2015-07-29T10:06:01.277"
    }
}

Version 1

If your application has a dependency on how sleep data was calculated in the version 1 endpoints, the previous documentation can be found here.