Create Sleep Log
chevron down

Create Sleep Log

Creates a log entry for a sleep event and returns a response in the format requested.

Scope: sleep


POST /1.2/user/[user-id]/sleep.json

URI Arguments
user-id required The encoded ID of the user. Use "-" (dash) for current logged-in user.

Query Parameters
date required Log entry date in the format yyyy-MM-dd. string ($date)
duration required Duration in milliseconds. integer
startTime required Start time; hours and minutes in the format HH:mm. string ($date)

Request Headers
authorization required Specify the token type and Fitbit user’s access token.
Token type: Bearer
accept optional Defines the media type of the response content the client is expecting.
Supported: application/json
accept-language optional The measurement unit system to use for response values. See Localization.
accept-locale optional The locale to use for response values. See Localization.
content-length required According to RFC 7230, section 3.3.2, this HTTP request requires the Content-Length header field containing the anticipated size of the payload body.

curl -X POST "" \
-H "accept: application/json" \
-H "authorization: Bearer <access_token>" \
-H "content-length: <message_body_size>"


Element Name Description
sleep : dateOfSleep The data the sleep log ended.
sleep : duration Length of the sleep in milliseconds.
sleep : efficiency Calculated sleep efficiency score. This is not the sleep score available in the mobile application.
sleep : endTime Time the sleep log ended.
sleep : infoCode
sleep : isMainSleep Boolean value: true or false
sleep : levels : data : dateTime Timestamp the user started in sleep level.
sleep : levels : data : level The sleep level the user entered.
sleep : levels : data : seconds The length of time the user was in the sleep level.
Displayed in seconds.
sleep : levels : summary : [stage] : count Total number of times the user entered the sleep level.
sleep : levels : summary : [stage] : minutes Total number of minutes the user appeared in the sleep level.
sleep : logId Sleep log ID.
sleep : minutesAfterWakeup The total number of minutes after the user woke up.
sleep : minutesAsleep The total number of minutes the user was asleep.
sleep : minutesAwake The total number of minutes the user was awake.
sleep : minutesToFallAsleep The total number of minutes before the user fell asleep.
sleep : startTime Time the sleep log begins.
sleep : timeInBed Total number of minutes the user was in bed.
sleep : type The type of sleep log.
Supported : classic | stages
  "sleep": {
    "dateOfSleep": "2020-02-09",
    "duration": 720000,
    "efficiency": 100,
    "endTime": "2020-02-09T22:12:00.000",
    "infoCode": 0,
    "isMainSleep": false,
    "levels": {
      "data": [
          "dateTime": "2020-02-09T22:00:00.000",
          "level": "asleep",
          "seconds": 720
      "summary": {
        "asleep": {
          "count": 0,
          "minutes": 12
        "awake": {
          "count": 0,
          "minutes": 0
        "restless": {
          "count": 0,
          "minutes": 0
    "logId": 25793948582,
    "minutesAfterWakeup": 0,
    "minutesAsleep": 12,
    "minutesAwake": 0,
    "minutesToFallAsleep": 0,
    "startTime": "2020-02-09T22:00:00.000",
    "timeInBed": 12,
    "type": "classic"

Response Headers
content-type The media type of the response content being sent to the client.
Supported: application/json
fitbit-rate-limit-limit The quota number of calls.
fitbit-rate-limit-remaining The number of calls remaining before hitting the rate limit.
fitbit-rate-limit-reset The number of seconds until the rate limit resets.
Note: The rate limit headers are approximate and asynchronously updated. This means that there may be a minor delay in the decrementing of remaining requests. This could result in your application receiving an unexpected 429 response if you don't track the total number of requests you make yourself.

Response Type
HTTP Status Code HTTP response code. List of codes are found in the Troubleshooting Guide.
Status Message Description of the status code.
Response Body Contains the JSON response to the API call. When errors are returned by the API call, the errorType, fieldName and message text will provide more information to the cause of the failure.

Response Codes
201 A successful request.
400 The request had bad syntax or was inherently impossible to be satisfied.
401 The request requires user authentication.
Note: For a complete list of response codes, please refer to the Troubleshooting Guide.

Additional Information

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:

  1. stages : Levels data is returned with 30-second granularity. 'Sleep Stages' levels include deep, light, rem, and wake.
  2. 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.

Manually Created Sleep Logs

A manual sleep log is either a sleep log that has human input through the mobile or web application, or a 3rd party application records sleep using the Create Sleep Log endpoint. When a sleep log is manually recorded, a "classic" sleep log is generated. Sleep "stage" logs use the device heart rate and movement to calculate sleep stage data. When manually entering a sleep log, this information is typically not available.