Sleep resources are segments of sleep that occur during a specific period of time.

Get a list of sleeps the user has
GET https://api.humanapi.co/v1/human/sleeps

Returns a single sleep
GET https://api.humanapi.co/v1/human/sleeps/{id}

# Returns a json array of sleeps:
[{
  "id": "551058f168d29c4133c4d1f4",
  "userId": "52e20cb2fff56aac62000001",
  "day": "2015-03-23",
  "startTime": "2015-03-23T02:50:27.000Z",
  "endTime": "2015-03-23T09:21:54.000Z",
  "tzOffset": "-07:00",
  "source": "jawbone",
  "mainSleep": true,
  "timeAsleep": 362,
  "timeAwake": 28,
  "efficiency": 57,
  "timeToFallAsleep": 12,
  "timeAfterWakeup": 0,
  "timeInBed": 391,
  "createdAt": "2015-03-23T18:18:25.687Z",
  "updatedAt": "2015-03-23T18:18:25.687Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}, {
  "id": "550facab68d29c4133b4cf18",
  "userId": "52e20cb2fff56aac62000001",
  "day": "2015-03-23",
  "startTime": "2015-03-22T23:07:33.000Z",
  "endTime": "2015-03-23T06:54:35.000Z",
  "tzOffset": "+01:00",
  "source": "jawbone",
  "mainSleep": true,
  "timeAsleep": 442,
  "timeAwake": 24,
  "efficiency": 80,
  "timeToFallAsleep": 4,
  "timeAfterWakeup": 0,
  "timeInBed": 467,
  "createdAt": "2015-03-23T06:03:23.091Z",
  "updatedAt": "2015-03-23T06:03:23.091Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}, {
  "id": "550f8daf68d29c4133b122b5",
  "userId": "52e20cb2fff56aac62000001",
  "day": "2015-03-22",
  "startTime": "2015-03-22T04:06:58.000Z",
  "endTime": "2015-03-22T13:36:10.000Z",
  "tzOffset": "-04:00",
  "source": "jawbone",
  "mainSleep": true,
  "timeAsleep": 377,
  "timeAwake": 180,
  "efficiency": 68,
  "timeToFallAsleep": 16,
  "timeAfterWakeup": 0,
  "timeInBed": 569,
  "createdAt": "2015-03-23T03:51:11.219Z",
  "updatedAt": "2015-03-23T03:51:11.219Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}]
# Get all sleeps associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/sleeps"

Response Properties

PropertyTypeDescription
idStringThe id of the resource.
userIdString[deprecated - use humanId]
humanIdStringUnique user identifier
dayDateThe day the sleep was recorded
startTimeDateThe original start date and time of the sleep segment in UTC time
endTimeDateThe original end date and time of the sleep segment in UTC time
tzOffsetStringThe offset from UTC time in +/-hh:mm (e.g. -04:00)
sourceStringThe source service for the measurement, where it was created
mainSleepBooleanA boolean value indicating if this sleep was the main sleep of the day (default true when not specified by source)
timeAsleepNumberThe time asleep during the segment (in minutes)
timeAwakeNumberThe time awake during the segment (in minutes)
efficiencyNumberThe efficiency score
timeToFallAsleepNumberThe number of minutes it took to fall asleep
timeAfterWakeupNumberThe number of minutes in bed after waking up
timeInBedNumberThe total number of minutes spent in bed
numberOfWakeupsNumberThe number of times the user woke up while in bed
updatedAtDateThe time the measurement was updated on the Human API server
createdAtDateThe time the measurement was created on the Human API server
timeSeriesObjectTime series data for the sleep, such as quality. See below for details

📘

Time Series

Add time_series=true to get time series data for sleeps. See below for details.

Query Parameters

ParameterDescription
time_seriesAdd time_series=true to get time series data for sleeps. See below for details

Time Series Object

The timeSeries object can have multiple embedded objects. In the example below there is one object called “quality”, some services might provide other properties such as “heartRate” or “breathing” etc.

The embedded objects have the following properties:

PropertyDescription
typeType of data, indexed with fixed time interval (See intervalInMillis) or timestamped.
intervalInMillisIf the type is indexed this indicates the number of milliseconds between each value.
valuesThe array of values, single values (indexed) or key-value pairs* (timestamped).

🚧

Timestamp represents the number of seconds from startTime.

Standard Series

Some series have standardized values across sources. Standard series are listed below.

SeriesValues
state0: wide awake, 1: awake, 2: light sleep, 3: regular sleep, 4: deep sleep, 5: REM sleep