GET
/
sleep
List sleep sessions
curl --request GET \
  --url http://healthkite.local:8080/sleep
{
  "from": "2026-04-11T00:00:00Z",
  "to": "2026-05-11T00:00:00Z",
  "sampleEncoding": "columnar-v1",
  "sources": [
    {
      "id": 0,
      "device": null
    }
  ],
  "sessions": [
    {
      "startDate": "2026-05-10T04:20:00Z",
      "endDate": "2026-05-10T13:31:30Z",
      "inBedDuration": 33090,
      "asleepDuration": 27660,
      "awakeDuration": 5430,
      "src": 0,
      "phases": {
        "inBed": {
          "t": [
            0
          ],
          "dur": [
            33090
          ]
        },
        "asleepCore": {
          "t": [
            5430,
            7950
          ],
          "dur": [
            1020,
            270
          ]
        },
        "asleepDeep": {
          "t": [
            6450
          ],
          "dur": [
            1500
          ]
        },
        "asleepREM": {
          "t": [
            9570,
            16590
          ],
          "dur": [
            1290,
            2940
          ]
        },
        "awake": {
          "t": [
            0
          ],
          "dur": [
            5430
          ]
        }
      }
    }
  ],
  "limit": 30,
  "offset": 0,
  "total": 47,
  "hasMore": true
}
HealthKit emits sleep as overlapping HKCategorySample records (one outer inBed envelope plus inner phase samples). This endpoint reconciles them into one session per night using a 2-hour gap threshold.

​
Query parameters

NameTypeDefaultRange
fromISO-8601 UTCto - 30 daysany
toISO-8601 UTCnowany
limitinteger301-365
offsetinteger0≥ 0

​
Phase keys

Apple’s HKCategoryValueSleepAnalysis mapped verbatim:
KeyMeaning
inBedOuter envelope (typically one entry = session length)
asleepCoreLight sleep
asleepDeepDeep / slow-wave sleep
asleepREMREM
asleepUnspecifiedPre-iOS-16 sleep samples + sources that don’t differentiate phases
awakeAwake periods within the in-bed window
Phase intervals encode as { t, dur } parallel arrays, integer seconds offset from session.startDate. Empty phases are omitted entirely.

​
Durations

FieldFormula
inBedDurationsum of inBed phase durations
asleepDurationsum of all asleep* durations (Core + Deep + REM + Unspecified)
awakeDurationsum of awake durations
Efficiency is asleepDuration / inBedDuration — computed client-side, not returned.

​
Reconciliation rules

  • Session boundary: samples are walked sorted by startDate. A new session starts when the gap from the current running endDate exceeds 2 hours.
  • Multi-source: when samples for a single session come from multiple sources (rare), the session’s src points at the most-frequent source. The top-level sources array collects all distinct sources across all sessions in the response.
  • Pre-iOS-16 data: deprecated asleep value maps to asleepUnspecified.

​
MCP tool

list_sleep_sessions({ "from": "2026-04-11T00:00:00Z", "to": "2026-05-11T00:00:00Z", "limit": 14 })

Query Parameters

​
from
string<date-time>

ISO-8601 UTC. Default: to - 30 days.

​
to
string<date-time>

ISO-8601 UTC. Default: now.

​
limit
integer
default:30
Required range: 1 <= x <= 365
​
offset
integer
default:0
Required range: x >= 0

Response

200 - application/json

Sleep sessions