Request sleep analysis data for a specific session.

1. Request

1.1 URL

GET https://api.asleep.ai/data/v2/sessions/{session_id}

1.2 Header

Field	Type	Required	Default	Description
x-api-key	String	O		API Key
x-user-id	String	O		Issued user id
timezone	String	X	UTC	Change the timezone of the analysis results to the corresponding timezone and return Yes. UTC, Asia/Seoul

1.3 Path parameter

Field	Type	Required	Description
session_id	String	O	id of the session in which you want to request data

Example

curl "https://api.asleep.ai/data/v2/sessions/{session_id}" -XGET \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "x-user-id: <USER_ID>"

2. Response

2.1 200 OK

Session details lookup success

2.1.1 Body (result field)

The state of the session and the terms of the agreement determine the nullable of the object and the object internal components.

if state != COMPLETE: stat object is null
if state == COMPLETE && validity != VALID: stat object is null

Field	Type	Description
timezone	String	Timezone
validity	String	Whether the analysis of that sleep session is valid. If some of the uploaded audio files are invalid, or if the percentage lost is more than a certain number, the analysis is inaccurate and displays a field 'IN_PROGRESS`: IF the session IS OPEN 'INVALID: TOO_MANDY_DEFECTS_IN_SLEEP_STAGES': NOT enough sleep phase analysis 'INVALID: TOO_MANY_DEFECTS_IN_OSA_STAGES': NOT enough sleep apnea analysis 'VALID': The analysis is valid
session	Session Object	Session Report Information
stat	Stat Object?	Session Report Information

2.1.2 Session Object

if state == OPEN: session_end_time is null
- if not use real-time analysis: sleep_stages is null
- if not use sleep apnea analysis: osa_stages is null
if state != OPEN
- if not use sleep apnea analysis: osa_stages is null

Field	Type	Description
id	String	session id
state	String (`OPEN`,`CLOSED`,`COMPLETE`)	Status of Session 'OPEN': An in-progress session, with audio uploads available 'CLOSED': The session terminated by sending an end session request. Unable to upload audio files. Analysis of uploaded sleep audio is still in progress 'COMPLETE': All sleep analysis completed after the end of the session
start_time	String (`YYYY-MM-DDThh:mm:ss+-hh:mm`)	Session start time Example) 2022-08-01T01:31: 17+09: 00 (If the request timezone is Asia/Seoul)
end_time	String (`YYYY-MM-DDThh:mm:ss+-hh:mm`)?	Session end time Example) 2022-08-01T01:31: 17+09: 00 (If the request timezone is Asia/Seoul)
sleep_stages	[Sleep Stages]?	Sleep Stages List
osa_stages	[OSA Stages]?	Sleep Apnea Stages List

2.1.3 Sleep Stages

sleep stage is-1,0,1,2,3 It is represented by an integer of one, and the number one represents the sleep stage of the 30-second interval. The meaning of each number is as shown in the table below

0(wake),1(sleep)if the terms of the agreement are 2-stage analysis

number	sleep stage
-1	error (invalid audio, analysis error, etc)
0	wake
1	light sleep
2	deep sleep
3	REM sleep

2.1.4 OSA Stages

osa stage (Apnea stage)is-1,0,1 It is represented by an integer of one, and the number one represents the sleep stage of the 30-second interval. The meaning of each number is as shown in the table below

number	osa stage
-1	error (invalid audio, analysis error, etc)
0	stable
1	unstable

2.1.5 Stat Object

For each metric details, please see Key Concepts

if state == COMPLETE
- If you use 2-stage analysis: only presents wake and sleep information: time_in_rem, time_in_light, time_in_deep, rem_ratio, light_ratio, deep_ratio is null
- if not use sleep apnea: time_in_stable_breath, time_in_unstable_breath, stable_breath_ratio, unstable_breath_ratio, breathing_pattern, estimated_ahi is null
- if all stages are wake(never slept session): didn't sleep: sleep_latency, sleep_time, wakeup_latency, wake_time, wake_ratio, sleep_ratio, rem_ratio, light_ratio, deep_ratio, stable_breath_ratio, unstable_breath_ratio, breathing_pattern, estimated_ahi is null

Field	Type	Description	Example
sleep_efficiency	float (`0~1 range, decimal points`)	The percentage of time you actually slept during sleep measurement	0.84
sleep_latency	int (`seconds`)?	Time to fall asleep	1800
sleep_time	String (`YYYY-MM-DDThh:mm:ss+-hh:mm`)?	The time it takes to fall asleep after the start of sleep staging	2022-08-01T00:30:00+09:00
wakeup_latency	int (`seconds`)?	The time it takes to wake up and end your sleep measurement	1800
wake_time	String (`YYYY-MM-DDThh:mm:ss+-hh:mm`)?	Wake time	2022-08-01T07:30:00+09:00
time_in_wake	int (`seconds`)	Wake time during sleep	2700
time_in_sleep_period	int (`seconds`)	During sleep measurement time, excluding the time it took from the start of the sleep measurement to fall asleep and the time it took from the wake to the end of the sleep measurement (time_in_bed - sleep_latency - wakeup_latency)	27000
time_in_sleep	int (`seconds`)	During sleep measurement time, the time you were actually sleeping This time is divided into three stages: deep,light,and rem	24300
time_in_bed	int (`seconds`)	The time from the start of the sleep measurement to the end of the sleep measurement	28800
time_in_rem	int (`seconds`)?	Total time the sleep phase progressed to rem	13500
time_in_light	int (`seconds`)?	Total time the sleep phase progressed to light	5400
time_in_deep	int (`seconds`)?	Total time the sleep phase progressed to deep	5400
time_in_stable_breath	int (`seconds`)?	Total time in the breathing stable section	24300
time_in_unstable_breath	int (`seconds`)?	Total time of breath instability	2700
wake_ratio	float (`0~1 range, decimal points`)?	Rate of waking time in the middle during sleep phase	0.1
sleep_ratio	float (`0~1 range, decimal points`)?	During sleep stage, sleep ratio, not wake	0.9
rem_ratio	float (`0~1 range, decimal points`)?	rem sleep ratio	0.5
light_ratio	float (`0~1 range, decimal points`)?	Rate of light sleep during sleep phase	0.2
deep_ratio	float (`0~1 range, decimal points`)?	Rate of deep sleep during sleep phase	0.2
stable_breath_ratio	float (`0~1 range, decimal points`)?	The percentage of time that was a breathing stable section during the sleep phase	0.9
unstable_breath_ratio	float (`0~1 range, decimal points`)?	The percentage of time during the sleep phase that there was a breathing instability section	0.1
breathing_pattern	String (`VERY_STABLE`,`STABLE`,`UNSTABLE`,`VERY_UNSTABLE`)?	Breathing Instability Level `VERY_STABLE`: Very stable `STABLE`: stable `UNSTABLE`: unstable `VERY_UNSTABLE`: very unstable	STABLE
estimated_ahi	float (`0~1 range, decimal points`)?	Values for determining respiratory instability levels	29.71

🚧
Medical Device Regulation Notice
Using terms like sleep apnea, apnea, hypopnea, AHI, on service and marketing materials could violate medical device regulations. To ensure compliance, we label it as 'Breathing Stability' at Asleep products.

{
  "detail": "ok",
  "result": {
    "timezone": "UTC",
    "validity": "VALID",
    "session": {
      "id": "20220821093117_hz82a",
      "state": "COMPLETE",
      "start_time": "2022-08-21T09:31:17+00:00",
      "end_time": "2022-08-21T09:56:17+00:00",
      "sleep_stages": [
        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1
      ],
      "osa_stages": [
        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
      ]
    },
    "stat": {
      "sleep_efficiency": 0.8,
      "sleep_latency": 300,
      "sleep_time": "2022-08-21T09:31:17+00:00",
      "wakeup_latency": 0,
      "wake_time": "2022-08-21T09:31:17+00:00",
      "time_in_wake": 0,
      "time_in_sleep": 1200,
      "time_in_bed": 1500,
      "time_in_sleep_period": 1200,
      "time_in_rem": 0,
      "time_in_light": 1200,
      "time_in_deep": 0,
      "time_in_stable_breath": 1200,
      "time_in_unstable_breath": 0,
      "wake_ratio": 0.0,
      "sleep_ratio": 1.0,
      "rem_ratio": 0.0,
      "light_ratio": 0.0,
      "deep_ratio": 0.0,
      "stable_breath_ratio": 1.0,
      "unstable_breath_ratio": 0.0,
      "breathing_pattern": "VERY_STABLE",
      "estimated_ahi": 0.0
    }
  }
}

2.2 400 Bad Request

timezone didn't come in correctly

{
	"detail": "The invalid timezone is provided"
}

2.3 404 Not Found

session_idif the corresponding session is not found

{
	"detail": "Unable to find the sleep session of id {session_id}"
}

2.4 422 Unprocessable Entity

session_idis not valid

{
	"detail": "The format of sleep session id 20230608020315_hz82 is not valid"
}

Get Single Session

1. Request

1.1 URL

1.2 Header

1.3 Path parameter

Example

2. Response

2.1 200 OK

2.1.1 Body (result field)

2.1.2 Session Object

2.1.3 Sleep Stages

2.1.4 OSA Stages

2.1.5 Stat Object

🚧
Medical Device Regulation Notice

2.2 400 Bad Request

2.3 404 Not Found

2.4 422 Unprocessable Entity

1. Request

1.1 URL

1.2 Header

1.3 Path parameter

Example

2. Response

2.1 200 OK

2.1.1 Body (result field)

2.1.2 Session Object

2.1.3 Sleep Stages

2.1.4 OSA Stages

2.1.5 Stat Object

🚧Medical Device Regulation Notice

2.2 400 Bad Request

2.3 404 Not Found

2.4 422 Unprocessable Entity

🚧
Medical Device Regulation Notice