Get Sleep Logs

The Get Sleep Logs endpoint returns a summary and list of a user's sleep log entries as well as minute by minute sleep entry data for a given day in the format requested. The endpoint response includes summary for all sleep log entries for the given day (including naps.) If you need to fetch data only for the user's main sleep event, you can send the request with isMainSleep=true or use a Time Series call.

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

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/28H22H/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 ("awake"), or 3 ("really awake").

{
    "sleep": [
        {
            "isMainSleep":true,
            "logId":29744,
            "efficiency":98,
            "startTime":"2011-06-16T00:00:00.000",
            "duration":28800000,
            "minutesToFallAsleep":0,
            "minutesAsleep":480,
            "minutesAwake":0,
            "minutesAfterWakeup":0,
            "awakeningsCount":0, // deprecated
            "awakeCount":0,
            "awakeDuration":0,
            "restlessCount":0,
            "restlessDuration":0,
            "timeInBed":480
            "minuteData":[
                {
                    "dateTime":"00:00:00",
                    "value":"3"
                },
                {
                    "dateTime":"00:01:00",
                    "value":"2"
                },
                {
                    "dateTime":"00:02:00",
                    "value":"1"
                },
                &amp;lt;...&amp;gt;
        },   
        {
            "isMainSleep":false,
            "logId":29745,
            "efficiency":93,
            "startTime":"2011-06-16T14:00:00.000",
            "duration":3600000,
            "minutesToFallAsleep":20,
            "minutesAsleep":38,
            "minutesAwake":0,
            "minutesAfterWakeup":2,
            "awakeningsCount":0,
            "awakeCount":0,
            "awakeDuration":0,
            "restlessCount":0,
            "restlessDuration":0,
            "timeInBed":60,
            "minuteData":[
                {
                    "dateTime":"14:00:00",
                    "value":"3"
                },
                &amp;lt;...&amp;gt;
            ]
        }
    ],
    "summary":{
        "totalMinutesAsleep":518,
        "totalSleepRecords":2,
        "totalTimeInBed":540
    }
}

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-versionThe 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-LanguageoptionalThe 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-versionThe API version, which is currently 1.
Example

POST https://api.fitbit.com/1/user/-/sleep/goal.json

POST Parameters

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

Sleep Time Series

Get Sleep Time Series

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/28H22H/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.

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 or entries for time periods that DO NOT originate from a tracker. Sleep log entries appear on website's sleep tracker interface according to 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 Response

{
    "sleep": {
        "isMainSleep": false,
        "logId": 29767,
        "efficiency": 98,
        "startTime": "2011-06-16T17:20:00.000",
        "duration": 6000000,
        "minutesToFallAsleep": 0,
        "minutesAsleep": 47,
        "minutesAwake": 24,
        "awakeningsCount": 10,
        "timeInBed": 100
    }
}

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.