Sleep Logs
chevron down
back search icon cancel search
 
 

Sleep Logs Version 1 (Deprecated)

Overview

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-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/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-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/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].jso
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 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:

GET https://api.fitbit.com/1/user/[user-id]/[resource-path]/date/[date]/[period].json
api-version The API version. Currently version 1.
user-id The encoded ID of the user. Use "-" (dash) for current logged-in user.
resource-path The resource path; see the Resource Path Options below for a list of options.
date The end date of the period specified in the format yyyy-MM-dd or today.
period The range for which data will be returned. Options are 1d, 7d, 30d, 1w, 1m, 3m, 6m, 1y, or max. 
GET https://api.fitbit.com/1/user/[user-id]/[resource-path]/date/[base-date]/[end-date].json
api-version The API version. Currently version 1.
user-id The encoded ID of the user. Use "-" (dash) for current logged-in user.
resource-path The resource path; see the Resource Path Options below for a list of options.
base-date The range start date, in the format yyyy-MM-dd or today.
end-date The 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

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

Request Headers

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