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.

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-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.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-idThe ID of the user. Use "-" (dash) for current logged-in user.
startDateThe date for the first sleep log to be returned. In the format yyyy-MM-dd. This date is inclusive
endDateThe 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-idThe encoded ID of the user. Use "-" (dash) for current logged-in user.
beforeDateThe 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.
afterDateThe 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.

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

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

Version 1

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