Version 1 (Deprecated)

These endpoints are deprecated and support for them may end unexpectedly. If your application does not depend on the sleep as calculated by these endpoints, please use the new v1.2 sleep endpoints.

Note: Version 1 APIs do not support Sleep Stages data

Get Sleep Logs by Date

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.

The relationship between sleep log entry properties is expressed with the following equation:

timeInBed = minutesToFallAsleep + minutesAsleep + minutesAwake + minutesAfterWakeup

Resource URL

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

URL parameters:

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

Example Request

GET https://api.fitbit.com/1/user/-/sleep/date/2014-09-01.json

Example Response

Note: The text within the brackets <> is a descriptive placeholder for a value or repeated elements. Also, values for minuteData can be 1 ("asleep"), 2 ("restless"), or 3 ("awake").

{
    "sleep": [
        {
            "isMainSleep": true,
            "logId":<value>,
            "efficiency":<value>,
            "startTime":"2011-06-16T00:00:00.000",
            "duration":<value in milliseconds>,
            "minutesToFallAsleep":<value>,
            "minutesAsleep":<value>,
            "minutesAwake":<value>,
            "minutesAfterWakeup":<value>,
            "awakeningsCount":<value>, // deprecated
            "awakeCount":<value>,
            "awakeDuration":<value>,
            "restlessCount":<value>,
            "restlessDuration":<value>,
            "timeInBed":<value in minutes>
            "minuteData":[
                {
                    "dateTime":"00:00:00",
                    "value":"3"
                },
                {
                    "dateTime":"00:01:00",
                    "value":"2"
                },
                {
                    "dateTime":"00:02:00",
                    "value":"1"
                },
                <...>
            ]
        },
        {
            "isMainSleep": false,
            "logId":<value>,
            "efficiency":<value>,
            "startTime":"2011-06-16T14:00:00.000",
            "duration":<value in milliseconds>,
            "minutesToFallAsleep":<value>,
            "minutesAsleep":<value>,
            "minutesAwake":<value>,
            "minutesAfterWakeup":<value>,
            "awakeningsCount":<value>,
            "awakeCount":<value>,
            "awakeDuration":<value>,
            "restlessCount":<value>,
            "restlessDuration":<value>,
            "timeInBed":<value in minutes>,
            "minuteData":[
                {
                    "dateTime":"14:00:00",
                    "value":"3"
                },
                <...>
            ]
        }
    ],
    "summary":{
        "totalMinutesAsleep": <value>,
        "totalSleepRecords": 2,
        "totalTimeInBed": <value in minutes>
    }
}

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.

Resource URL

POST https://api.fitbit.com/1/user/[user-id]/sleep.json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.

POST Parameters

startTimerequiredStart time; hours and minutes in the format HH:mm.
durationrequiredDuration in milliseconds.
daterequiredLog entry date in the format yyyy-MM-dd.

Example Request

POST https://api.fitbit.com/1/user/-/sleep.json?date=2017-03-27&startTime=19:55&duration=7200000

Example Response

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

{
    "sleep": {
        "awakeCount": 0,
        "awakeDuration": 0,
        "awakeningsCount": 0,
        "dateOfSleep": "2017-03-28",
        "duration": 7200000,
        "efficiency": 100,
        "isMainSleep": false,
        "logId": 10183454484,
        "minuteData": [
            {
                "dateTime": "02:32:00",
                "value": "1"
            },
            {
                "dateTime": "02:33:00",
                "value": "1"
            },
            {
                "dateTime": "02:34:00",
                "value": "1"
            },
            {
                "dateTime": "02:35:00",
                "value": "1"
            },
            {
                "dateTime": "02:36:00",
                "value": "1"
            },
            <...>
        ],
        "minutesAfterWakeup": 0,
        "minutesAsleep": 120,
        "minutesAwake": 0,
        "minutesToFallAsleep": 0,
        "restlessCount": 0,
        "restlessDuration": 0,
        "startTime": "2017-03-28T02:32:00.000",
        "timeInBed": 120
    }
}

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-idThe encoded ID of the user. Use "-" (dash) for current logged-in user.
log-idID of the sleep log to be deleted.

Response

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

Sleep Time Series (Deprecated)

Note: This API has been deprecated with the introduction of version 1.2 of the Sleep APIs described above. Sleep Stages data cannot be retrieved with this API. If your application requires data consistency while you transition over to the version 1.2 Sleep APIs, you can get this data through the version 1 Get Sleep Logs by Date endpoint.

The Get Sleep Time Series endpoint returns time series data in the specified range for a given resource in the format requested using units in the unit system that corresponds to the Accept-Language header provided.

Note: Even if you provide earlier dates in the request, the response retrieves only data since the user's join date or the first log entry date for the requested collection.

Resource URL

There are two acceptable formats for retrieving intraday data:

1) GET https://api.fitbit.com/1/user/[user-id]/[resource-path]/date/[date]/[period].json

api-versionThe API version. Currently version 1.
user-idThe encoded ID of the user. Use "-" (dash) for current logged-in user.
resource-pathThe resource path; see the Resource Path Options below for a list of options.
dateThe end date of the period specified in the format yyyy-MM-dd or today.
periodThe range for which data will be returned. Options are 1d, 7d, 30d, 1w, 1m, 3m, 6m, 1y, or max.


2) GET https://api.fitbit.com/1/user/[user-id]/[resource-path]/date/[base-date]/[end-date].json

api-versionThe API version. Currently version 1.
user-idThe encoded ID of the user. Use "-" (dash) for current logged-in user.
resource-pathThe resource path; see the Resource Path Options below for a list of options.
base-dateThe range start date, in the format yyyy-MM-dd or today.
end-dateThe end date of the range.

Resource Path Options

sleep/startTime  
sleep/timeInBed  
sleep/minutesAsleep  
sleep/awakeningsCount  
sleep/minutesAwake  
sleep/minutesToFallAsleep  
sleep/minutesAfterWakeup  
sleep/efficiency

Example Requests

1) GET https://api.fitbit.com/1/user/-/sleep/minutesAsleep/date/today/2014-09-01.json

2) GET https://api.fitbit.com/1/user/-/sleep/minutesAsleep/date/2014-09-01/today.json

Request Headers

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