---
title: "Get Sleep"
method: GET
path: "/queries/sleeps/{sleep_id}"
tags: ["Queries / Sleep"]
---

# Get Sleep

`GET /queries/sleeps/{sleep_id}`

This endpoint returns sleep data including different sleep stages that represent the various phases of sleep a person goes through during a sleep cycle. Each stage is characterized by distinct physiological and neurological patterns.

The different sleep stages are:

- **awake**: The state of being fully conscious and alert.
- **sleeping**: A general term for being in a state of sleep.
- **out_of_bed**: The state when a person is not in bed, possibly indicating a brief interruption in sleep.
- **light**: A stage of sleep where the body begins to relax, and the heart rate slows down. It is easier to wake up from this stage.
- **deep**: A restorative stage of sleep where the body repairs and regrows tissues, builds bone and muscle, and strengthens the immune system.
- **rem**: Rapid Eye Movement sleep, a stage where dreaming occurs, and the brain is very active. It plays a role in memory consolidation and mood regulation.
- **awake_in_bed**: The state of being awake while still in bed, often occurring before falling asleep or after waking up.
- **nap**: A short sleep, typically taken during the day, that can help improve alertness and performance.
- **unknown**: A stage that cannot be classified into any of the known categories, possibly due to insufficient data or anomalies in the sleep pattern.


### Sleep Attribution Date

The sleep date attribution follows two simple rules to determine which date a sleep record should be associated with:

1. **Provider Payload Date**: The primary source of truth is the date provided in the payload from the sleep tracking provider. This date is used if available.

2. **End Date Rule**: If the provider payload date is not available, the sleep date is attributed to the day on which the sleep session ended.

This straightforward approach ensures consistent date attribution for sleep records, regardless of when the sleep session started or ended.


### Main Sleep and Nap

There are two types of sleep: main sleep and nap. There can be only one main sleep per day, which is the longest sleep period. A nap is a shorter sleep taken during the day and will have a `sleep_duration_nap` value.


### Sleep Durations

Total sleep duration is the sum of the durations of light, deep, and REM sleep stages, while total time in bed also includes time spent awake.
```
total sleep = light + deep + rem
time in bed = total sleep + awake
```
Note that nap time is not included in the total sleep time for a day.
Sleep latency refers to the estimated time from when rest begins until the first occurrence of light or deep sleep. The accuracy of sleep stages and latency depends entirely on the provider’s sensors and calculations.
Sleep duration values are reported in milliseconds.

## Path parameters

- `sleep_id` string, required — Sleep ID

## Query parameters

- `include_stages` boolean — Include stages
- `include_samples` boolean — Include samples

## Response `200`

OK

- QueryOutputSleep
  - `duration` integer — Record duration
  - `end_at_timestamp` string, date-time — Record end time
  - `input_method` 'unknown' | 'manual' | 'device' — Data input method
  - `metrics` object — Metrics output
    - `air_temperature` number — air_temperature in celsius
    - `air_temperature_max` number — air_temperature_max in celsius
    - `air_temperature_min` number — air_temperature_min in celsius
    - `ascent` number — ascent in meters
    - `basal_body_temperature` number — basal_body_temperature in celsius
    - `basal_body_temperature_max` number — basal_body_temperature_max in celsius
    - `basal_body_temperature_min` number — basal_body_temperature_min in celsius
    - `bedtime_duration` number — bedtime_duration in ms
    - `blood_pressure_diastolic` number — blood_pressure_diastolic in mmHg
    - `blood_pressure_diastolic_max` number — blood_pressure_diastolic_max in mmHg
    - `blood_pressure_diastolic_min` number — blood_pressure_diastolic_min in mmHg
    - `blood_pressure_systolic` number — blood_pressure_systolic in mmHg
    - `blood_pressure_systolic_max` number — blood_pressure_systolic_max in mmHg
    - `blood_pressure_systolic_min` number — blood_pressure_systolic_min in mmHg
    - `body_bone_mass` number — body_bone_mass in g
    - `body_fat` number — body_fat in percentage
    - `body_fat_max` number — body_fat_max in percentage
    - `body_fat_min` number — body_fat_min in percentage
    - `body_mass_index` number — body_mass_index in count
    - `body_temperature` number — body_temperature in celsius
    - `body_temperature_max` number — body_temperature_max in celsius
    - `body_temperature_min` number — body_temperature_min in celsius
    - `breathing_rate` number — breathing_rate in breaths/min
    - `breathing_rate_max` number — breathing_rate_max in breaths/min
    - `breathing_rate_min` number — breathing_rate_min in breaths/min
    - `cadence` number — cadence in rpm
    - `cadence_max` number — cadence_max in rpm
    - `cadence_min` number — cadence_min in rpm
    - `calories_burned` number — calories_burned in kcal
    - `calories_burned_active` number — calories_burned_active in kcal
    - `calories_burned_basal` number — calories_burned_basal in kcal
    - `calories_intake` number — calories_intake in kcal
    - `descent` number — descent in meters
    - `distance` number — distance in meters
    - `distance_cycling` number — distance_cycling in meters
    - `distance_running` number — distance_running in meters
    - `distance_swimming` number — distance_swimming in meters
    - `distance_walking` number — distance_walking in meters
    - `distance_wheelchair` number — distance_wheelchair in meters
    - `duration_active` number — duration_active in ms
    - `duration_high_intensity` number — duration_high_intensity in ms
    - `duration_low_intensity` number — duration_low_intensity in ms
    - `duration_moderate_intensity` number — duration_moderate_intensity in ms
    - `ecg_rri` number — ecg_rri in ms
    - `ecg_voltage` number — ecg_voltage in uV
    - `elevation` number — elevation in meters
    - `elevation_gain` number — elevation_gain in meters
    - `elevation_loss` number — elevation_loss in meters
    - `elevation_max` number — elevation_max in meters
    - `elevation_min` number — elevation_min in meters
    - `floors_climbed` number — floors_climbed in count
    - `glucose` number — glucose in mg/dL
    - `heartrate` number — heartrate in bpm
    - `heartrate_max` number — heartrate_max in bpm
    - `heartrate_min` number — heartrate_min in bpm
    - `heartrate_resting` number — heartrate_resting in bpm
    - `heartrate_resting_max` number — heartrate_resting_max in bpm
    - `heartrate_resting_min` number — heartrate_resting_min in bpm
    - `heartrate_zone0_duration` number — heartrate_zone0_duration in ms
    - `heartrate_zone1_duration` number — heartrate_zone1_duration in ms
    - `heartrate_zone2_duration` number — heartrate_zone2_duration in ms
    - `heartrate_zone3_duration` number — heartrate_zone3_duration in ms
    - `heartrate_zone4_duration` number — heartrate_zone4_duration in ms
    - `heartrate_zone5_duration` number — heartrate_zone5_duration in ms
    - `height` number — height in meters
    - `hrv_rmssd` number — hrv_rmssd in ms
    - `hrv_sdnn` number — hrv_sdnn in ms
    - `latitude` number — latitude in degrees
    - `longitude` number — longitude in degrees
    - `pace` number — pace in sec/m
    - `power` number — power in w
    - `power_max` number — power_max in w
    - `skin_temperature` number — skin_temperature in celsius
    - `skin_temperature_max` number — skin_temperature_max in celsius
    - `skin_temperature_min` number — skin_temperature_min in celsius
    - `sleep_breathing_rate` number — sleep_breathing_rate in breaths/min
    - `sleep_breathing_rate_max` number — sleep_breathing_rate_max in breaths/min
    - `sleep_breathing_rate_min` number — sleep_breathing_rate_min in breaths/min
    - `sleep_duration` number — sleep_duration in ms
    - `sleep_duration_awake` number — sleep_duration_awake in ms
    - `sleep_duration_deep` number — sleep_duration_deep in ms
    - `sleep_duration_light` number — sleep_duration_light in ms
    - `sleep_duration_nap` number — sleep_duration_nap in ms
    - `sleep_duration_rem` number — sleep_duration_rem in ms
    - `sleep_efficiency` number — sleep_efficiency in percentage
    - `sleep_interruptions` number — sleep_interruptions in count
    - `sleep_latency` number — sleep_latency in ms
    - `sleep_score` number — sleep_score in percentage
    - `sleep_skin_temperature_deviation` number — sleep_skin_temperature_deviation in celsius
    - `speed` number — speed in m/sec
    - `speed_max` number — speed_max in m/sec
    - `speed_min` number — speed_min in m/sec
    - `spo2` number — spo2 in percentage
    - `spo2_max` number — spo2_max in percentage
    - `spo2_min` number — spo2_min in percentage
    - `steps` number — steps in count
    - `swimming_distance_per_stroke` number — swimming_distance_per_stroke in meters
    - `swimming_lengths` number — swimming_lengths in count
    - `vo2max` number — vo2max in mL/kg/min
    - `wakeup_latency` number — wakeup_latency in ms
    - `weight` number — weight in g
  - `modified_at` string, date-time, required — Modified at
  - `provider_slug` string — Provider slugs
  - `record_ids` string[], nullable
  - `samples` QueryOutputActivitySleepSamples
    - `durations` integer[], nullable
    - `offsets` integer[], nullable
    - `values` object
      - `air_temperature` number[]
      - `air_temperature_max` number[]
      - `air_temperature_min` number[]
      - `ascent` number[]
      - `basal_body_temperature` number[]
      - `basal_body_temperature_max` number[]
      - `basal_body_temperature_min` number[]
      - `bedtime_duration` number[]
      - `blood_pressure_diastolic` number[]
      - `blood_pressure_diastolic_max` number[]
      - `blood_pressure_diastolic_min` number[]
      - `blood_pressure_systolic` number[]
      - `blood_pressure_systolic_max` number[]
      - `blood_pressure_systolic_min` number[]
      - `body_bone_mass` number[]
      - `body_fat` number[]
      - `body_fat_max` number[]
      - `body_fat_min` number[]
      - `body_mass_index` number[]
      - `body_temperature` number[]
      - `body_temperature_max` number[]
      - `body_temperature_min` number[]
      - `breathing_rate` number[]
      - `breathing_rate_max` number[]
      - `breathing_rate_min` number[]
      - `cadence` number[]
      - `cadence_max` number[]
      - `cadence_min` number[]
      - `calories_burned` number[]
      - `calories_burned_active` number[]
      - `calories_burned_basal` number[]
      - `calories_intake` number[]
      - `descent` number[]
      - `distance` number[]
      - `distance_cycling` number[]
      - `distance_running` number[]
      - `distance_swimming` number[]
      - `distance_walking` number[]
      - `distance_wheelchair` number[]
      - `duration_active` number[]
      - `duration_high_intensity` number[]
      - `duration_low_intensity` number[]
      - `duration_moderate_intensity` number[]
      - `ecg_rri` number[]
      - `ecg_voltage` number[]
      - `elevation` number[]
      - `elevation_gain` number[]
      - `elevation_loss` number[]
      - `elevation_max` number[]
      - `elevation_min` number[]
      - `floors_climbed` number[]
      - `glucose` number[]
      - `heartrate` number[]
      - `heartrate_max` number[]
      - `heartrate_min` number[]
      - `heartrate_resting` number[]
      - `heartrate_resting_max` number[]
      - `heartrate_resting_min` number[]
      - `heartrate_zone0_duration` number[]
      - `heartrate_zone1_duration` number[]
      - `heartrate_zone2_duration` number[]
      - `heartrate_zone3_duration` number[]
      - `heartrate_zone4_duration` number[]
      - `heartrate_zone5_duration` number[]
      - `height` number[]
      - `hrv_rmssd` number[]
      - `hrv_sdnn` number[]
      - `latitude` number[]
      - `longitude` number[]
      - `pace` number[]
      - `power` number[]
      - `power_max` number[]
      - `skin_temperature` number[]
      - `skin_temperature_max` number[]
      - `skin_temperature_min` number[]
      - `sleep_breathing_rate` number[]
      - `sleep_breathing_rate_max` number[]
      - `sleep_breathing_rate_min` number[]
      - `sleep_duration` number[]
      - `sleep_duration_awake` number[]
      - `sleep_duration_deep` number[]
      - `sleep_duration_light` number[]
      - `sleep_duration_nap` number[]
      - `sleep_duration_rem` number[]
      - `sleep_efficiency` number[]
      - `sleep_interruptions` number[]
      - `sleep_latency` number[]
      - `sleep_score` number[]
      - `sleep_skin_temperature_deviation` number[]
      - `speed` number[]
      - `speed_max` number[]
      - `speed_min` number[]
      - `spo2` number[]
      - `spo2_max` number[]
      - `spo2_min` number[]
      - `steps` number[]
      - `swimming_distance_per_stroke` number[]
      - `swimming_lengths` number[]
      - `vo2max` number[]
      - `wakeup_latency` number[]
      - `weight` number[]
  - `score` integer
  - `sleep_date` string, date — Calendar date for which the sleep is attributed
  - `sleep_id` string, byte
  - `source` QueryOutputSourceInfo
    - `device_manufacturer` string
    - `device_model` string
    - `device_product` string
    - `device_version` string
    - `source_bundle_identifier` string
    - `source_os_version` string
    - `source_product` string
    - `source_version` string
  - `stages` QueryOutputSleepStage[], nullable
    - `duration` integer
    - `end_at` string, date-time
    - `metrics` object — Metrics output
      - `air_temperature` number — air_temperature in celsius
      - `air_temperature_max` number — air_temperature_max in celsius
      - `air_temperature_min` number — air_temperature_min in celsius
      - `ascent` number — ascent in meters
      - `basal_body_temperature` number — basal_body_temperature in celsius
      - `basal_body_temperature_max` number — basal_body_temperature_max in celsius
      - `basal_body_temperature_min` number — basal_body_temperature_min in celsius
      - `bedtime_duration` number — bedtime_duration in ms
      - `blood_pressure_diastolic` number — blood_pressure_diastolic in mmHg
      - `blood_pressure_diastolic_max` number — blood_pressure_diastolic_max in mmHg
      - `blood_pressure_diastolic_min` number — blood_pressure_diastolic_min in mmHg
      - `blood_pressure_systolic` number — blood_pressure_systolic in mmHg
      - `blood_pressure_systolic_max` number — blood_pressure_systolic_max in mmHg
      - `blood_pressure_systolic_min` number — blood_pressure_systolic_min in mmHg
      - `body_bone_mass` number — body_bone_mass in g
      - `body_fat` number — body_fat in percentage
      - `body_fat_max` number — body_fat_max in percentage
      - `body_fat_min` number — body_fat_min in percentage
      - `body_mass_index` number — body_mass_index in count
      - `body_temperature` number — body_temperature in celsius
      - `body_temperature_max` number — body_temperature_max in celsius
      - `body_temperature_min` number — body_temperature_min in celsius
      - `breathing_rate` number — breathing_rate in breaths/min
      - `breathing_rate_max` number — breathing_rate_max in breaths/min
      - `breathing_rate_min` number — breathing_rate_min in breaths/min
      - `cadence` number — cadence in rpm
      - `cadence_max` number — cadence_max in rpm
      - `cadence_min` number — cadence_min in rpm
      - `calories_burned` number — calories_burned in kcal
      - `calories_burned_active` number — calories_burned_active in kcal
      - `calories_burned_basal` number — calories_burned_basal in kcal
      - `calories_intake` number — calories_intake in kcal
      - `descent` number — descent in meters
      - `distance` number — distance in meters
      - `distance_cycling` number — distance_cycling in meters
      - `distance_running` number — distance_running in meters
      - `distance_swimming` number — distance_swimming in meters
      - `distance_walking` number — distance_walking in meters
      - `distance_wheelchair` number — distance_wheelchair in meters
      - `duration_active` number — duration_active in ms
      - `duration_high_intensity` number — duration_high_intensity in ms
      - `duration_low_intensity` number — duration_low_intensity in ms
      - `duration_moderate_intensity` number — duration_moderate_intensity in ms
      - `ecg_rri` number — ecg_rri in ms
      - `ecg_voltage` number — ecg_voltage in uV
      - `elevation` number — elevation in meters
      - `elevation_gain` number — elevation_gain in meters
      - `elevation_loss` number — elevation_loss in meters
      - `elevation_max` number — elevation_max in meters
      - `elevation_min` number — elevation_min in meters
      - `floors_climbed` number — floors_climbed in count
      - `glucose` number — glucose in mg/dL
      - `heartrate` number — heartrate in bpm
      - `heartrate_max` number — heartrate_max in bpm
      - `heartrate_min` number — heartrate_min in bpm
      - `heartrate_resting` number — heartrate_resting in bpm
      - `heartrate_resting_max` number — heartrate_resting_max in bpm
      - `heartrate_resting_min` number — heartrate_resting_min in bpm
      - `heartrate_zone0_duration` number — heartrate_zone0_duration in ms
      - `heartrate_zone1_duration` number — heartrate_zone1_duration in ms
      - `heartrate_zone2_duration` number — heartrate_zone2_duration in ms
      - `heartrate_zone3_duration` number — heartrate_zone3_duration in ms
      - `heartrate_zone4_duration` number — heartrate_zone4_duration in ms
      - `heartrate_zone5_duration` number — heartrate_zone5_duration in ms
      - `height` number — height in meters
      - `hrv_rmssd` number — hrv_rmssd in ms
      - `hrv_sdnn` number — hrv_sdnn in ms
      - `latitude` number — latitude in degrees
      - `longitude` number — longitude in degrees
      - `pace` number — pace in sec/m
      - `power` number — power in w
      - `power_max` number — power_max in w
      - `skin_temperature` number — skin_temperature in celsius
      - `skin_temperature_max` number — skin_temperature_max in celsius
      - `skin_temperature_min` number — skin_temperature_min in celsius
      - `sleep_breathing_rate` number — sleep_breathing_rate in breaths/min
      - `sleep_breathing_rate_max` number — sleep_breathing_rate_max in breaths/min
      - `sleep_breathing_rate_min` number — sleep_breathing_rate_min in breaths/min
      - `sleep_duration` number — sleep_duration in ms
      - `sleep_duration_awake` number — sleep_duration_awake in ms
      - `sleep_duration_deep` number — sleep_duration_deep in ms
      - `sleep_duration_light` number — sleep_duration_light in ms
      - `sleep_duration_nap` number — sleep_duration_nap in ms
      - `sleep_duration_rem` number — sleep_duration_rem in ms
      - `sleep_efficiency` number — sleep_efficiency in percentage
      - `sleep_interruptions` number — sleep_interruptions in count
      - `sleep_latency` number — sleep_latency in ms
      - `sleep_score` number — sleep_score in percentage
      - `sleep_skin_temperature_deviation` number — sleep_skin_temperature_deviation in celsius
      - `speed` number — speed in m/sec
      - `speed_max` number — speed_max in m/sec
      - `speed_min` number — speed_min in m/sec
      - `spo2` number — spo2 in percentage
      - `spo2_max` number — spo2_max in percentage
      - `spo2_min` number — spo2_min in percentage
      - `steps` number — steps in count
      - `swimming_distance_per_stroke` number — swimming_distance_per_stroke in meters
      - `swimming_lengths` number — swimming_lengths in count
      - `vo2max` number — vo2max in mL/kg/min
      - `wakeup_latency` number — wakeup_latency in ms
      - `weight` number — weight in g
    - `stage` 'awake' | 'sleeping' | 'out_of_bed' | 'light' | 'deep' | 'rem' | 'awake_in_bed' | 'nap' | 'in_bed' | 'unknown' — Sleep stages
    - `start_at` string, date-time
  - `start_at_timestamp` string, date-time, required — Record start time
  - `user_time_offset_minutes` integer — User time offset in minutes

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `422` — Unprocessable Entity
- `500` — Internal Server Error

---

[API](https://skmtc.dev/spikeapi/apis/application-user-api.md) · [All operations](https://skmtc.dev/spikeapi/apis/application-user-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/spikeapi/application-user-api/revisions/637338fb0c9d/schema)