Request sleep analysis data for a specific session.

1. Request

1.1 URL

GET https://api.asleep.ai/data/v3/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 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 contract of customer determine the nullable of the stat object

if peculiarities == IN_PROGRESS or NO_REALTIME_POLLING or TOO_SHORT_FOR_ANALYSIS or TOO_MANY_DEFECTS_IN_SLEEP_STAGES: stat object is null

Field	Type	Description
timezone	String	Timezone (Timezone List)
peculiarities	List	A field for describing any specific details or peculiarities of the sleep session. This field can include multiple labels below. `IN_PROGRESS`: If the session is OPEN, CLOSED `NEVER_SLEPT`: If it is determined that there was no sleep at all during the session measurement time `TOO_SHORT_FOR_ANALYSIS`: When the measurement time is too short to conduct a valid analysis (currently less than 20 minutes) `TOO_LONG_FOR_ANALYSIS`: Analysis has been conducted successfully, but the session measurement time is excessively long, making it difficult to trust (currently exceeding 24 hours) `TOO_MANY_DEFECTS_IN_SLEEP_STAGES`: When the error rate is high due to factors like missing audio uploads, resulting in insufficient sleep analysis results. `NO_BREATHING_STABILITY`: When the customer's contract conditions do not support breathing stability analysis. `NO_REALTIME_POLLING`: When, according to the customer's contract, real-time access to sleep information is not available.
missing_data_ratio	float(`0~1 range, decimal points`)	The error rate in sleep analysis results due to reasons such as missing audio uploads
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 peculiarities == NO_REALTIME_POLLING: sleep_stages is null
if peculiarities == NO_BREATHING_STABILITY: breath_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)
unexpected_end_time	String (`YYYY-MM-DDThh:mm:ss+-hh:mm`)?	If a session fails to proceed and terminate properly due to app crashes or similar issues, and the client later ends the session with an unexpected parameter set to 1, the time at which this happens is recorded. In this case, the "end_time" is calculated based on the sequence number of the last uploaded audio file. Therefore, if "end_time" is not null, it indicates an abnormal session.
created_timezone	String	Timezone of session creation (Timezone List)
sleep_stages	[Sleep Stages]?	Sleep Stages List
breath_stages	[Breath Stages]?	Breath Stability Stages List
snoring_stages	[Snoring Stages]?	Snoring 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 shown in the table below.

0(wake), 1(sleep) if you use 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 Breath Stages

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

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

2.1.5 Snoring Stages

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

number	snoring stage
-1	error (invalid audio, analysis error, etc)
0	no snoring
1	snoring

2.1.6 Stat Object

For each metric detail, 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, light_latency, deep_latency, rem_latency is null
- if peculiarities == NO_BREATHING_STABILITY: time_in_stable_breath, time_in_unstable_breath, stable_breath_ratio, unstable_breath_ratio, breathing_pattern, breathing_index, unstable_breath_count is null
- if peculiarities == NEVER_SLEPT: 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, breathing_index, light_latency, deep_latency, rem_latency, sleep_cycle, longest_waso, sleep_index is null
Newly added metrics do not support data from previous sessions. You can check the time when metrics were added at https://docs.asleep.ai/changelog.

Field	Type	Description	Example
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
wake_time	String (`YYYY-MM-DDThh:mm:ss+-hh:mm`)?	Wake time	2022-08-01T07:30:00+09:00
sleep_index	Int(`50 <= sleep_index <= 100`)?	(Beta) Test Operation Sleep Data	87
sleep_latency	Int (`seconds`)?	Time to fall asleep	1800
wakeup_latency	Int (`seconds`)?	The time it takes to wake up and end your sleep measurement	1800
light_latency	Int(`seconds`)?	The time it takes to the first Light after the start of sleep.
deep_latency	Int(`seconds`)?	The time it takes to the first Deep after the start of sleep.
rem_latency	Int(`seconds`)?	The time it takes to the first REM after the start of sleep.
time_in_bed	Int (`seconds`)	The time from the start of the sleep measurement to the end of the sleep measurement	28800
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_wake	Int (`seconds`)	Wake time during sleep	2700
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_rem	Int (`seconds`)?	Total time the sleep phase progressed to rem	13500
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
time_in_snoring	Int?	Total time of snoring	5400
time_in_no_snoring	Int?	Total time of no snoring	23400
sleep_efficiency	float (`0~1 range, decimal points`)	The percentage of time you actually slept during sleep measurement	0.84
sleep_ratio	float (`0~1 range, decimal points`)?	During sleep stage, sleep ratio, not wake	0.9
wake_ratio	float (`0~1 range, decimal points`)?	Rate of waking time in the middle during sleep phase	0.1
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
rem_ratio	float (`0~1 range, decimal points`)?	rem sleep ratio	0.5
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
snoring_ratio	float (`0~1 range, decimal points`)?	The percentage of time during the sleep phase that there was a snoring section	0.3
no_snoring_ratio	float (`0~1 range, decimal points`)?	The percentage of time during the sleep phase that there was no snoring.	0.7
breathing_index	float (`0~1 range, decimal points`)?	Values for determining respiratory instability levels	29.71
breathing_pattern	String (`STABLE_BREATH`,`MILDLY_UNSTABLE_BREATH`,`MODERATELY_UNSTABLE_BREATH`, `SEVERELY_UNSTABLE_BREATH`)?	Breathing Instability Level `STABLE_BREATH`: stable `MILDLY_UNSTABLE_BREATH`: mildly unstable `MODERTATELY_UNSTABLE_BREATH`: moderately unstable `SEVERELY_UNSTABLE_BREATH`: severely unstable	STABLE_BREATH
waso_count	Int?	The number of times 'wake' occurred during the sleep period	10
longest_waso	Int(`seconds`)?	The duration of the longest 'wake' during the sleep period	300
sleep_cycle_count	Int?	The number of sleep cycles.	4
sleep_cycle	Int(`seconds`)?	The average duration of one sleep cycle.	6600
sleep_cycle_time	List of String(`YYYY-MM-DDThh:mm:ss+-hh:mm`)	Transition time for sleep cycles [First sleep cycle onset time, first sleep cycle end time, second sleep cycle end time, ..., last sleep cycle end time]	["2023-09-05T16:15:00+00:00", "2023-09-05T18:03:00+00:00", "2023-09-05T20:32:30+00:00"]
unstable_breath_count	Int?	The number of times unstable breathing occurred.
snoring_count	Int?	The number of times snoring occurred.

{
    "detail": "OK",
    "result": {
        "timezone": "UTC",
        "peculiarities": [],
				"missing_data_ratio": 0.02,
        "session": {
            "id": "20230101000000_e5rsv",
            "state": "COMPLETE",
            "start_time": "2023-01-01T00:00:00+00:00",
            "end_time": "2023-01-01T00:20:00+00:00",
            "unexpected_end_time": null,
            "created_timezone": "UTC",
            "sleep_stages": [
                1,
                1,
                0,
                1,
                3,
                1,
                1,
                2,
                2,
                0,
                3,
                1,
                3,
                1,
                3,
                1,
                0,
                0,
                3,
                2,
                0,
                1,
                0,
                0,
                0,
                0,
                2,
                0,
                2,
                2,
                2,
                2,
                1,
                3,
                1,
                1,
                2,
                2,
                3,
                3
            ],
            "breath_stages": [
                1,
                0,
                0,
                1,
                1,
                1,
                0,
                1,
                0,
                1,
                1,
                1,
                1,
                0,
                0,
                1,
                0,
                1,
                1,
                1,
                1,
                1,
                1,
                0,
                0,
                1,
                0,
                1,
                0,
                1,
                1,
                1,
                1,
                1,
                1,
                0,
                0,
                1,
                0,
                1
            ],
            "snoring_stages": [
                1,
                0,
                0,
                1,
                1,
                1,
                0,
                1,
                0,
                1,
                1,
                1,
                1,
                0,
                0,
                1,
                0,
                1,
                1,
                1,
                1,
                1,
                1,
                0,
                0,
                1,
                0,
                1,
                0,
                1,
                1,
                1,
                1,
                1,
                1,
                0,
                0,
                1,
                0,
                1
            ]
        },
        "stat": {
            "sleep_time": "2023-01-01T00:00:00+00:00",
            "wake_time": "2023-01-01T00:20:00+00:00",
            "sleep_index": 85,
            "sleep_latency": 0,
            "wakeup_latency": 0,
            "light_latency": 300,
            "deep_latency": 600,
            "rem_latency": 900,
            "time_in_bed": 1200,
            "time_in_sleep_period": 1200,
            "time_in_sleep": 900,
            "time_in_wake": 300,
            "time_in_light": 360,
            "time_in_deep": 300,
            "time_in_rem": 240,
            "time_in_stable_breath": 420,
            "time_in_unstable_breath": 780,
            "time_in_snoring": 5400,
            "time_in_no_snoring": 23400,
            "sleep_efficiency": 0.75,
            "sleep_ratio": 0.75,
            "wake_ratio": 0.25,
            "light_ratio": 0.3,
            "deep_ratio": 0.25,
            "rem_ratio": 0.2,
            "stable_breath_ratio": 0.35,
            "unstable_breath_ratio": 0.65,
            "snoring_ratio": 0.3,
            "no_snoring_ratio": 0.7,
            "breathing_index": 64.83,
            "breathing_pattern": "SEVERELY_UNSTABLE_BREATH",
            "waso_count": 10,
            "longest_waso": 300,
            "sleep_cycle_count": 4,
            "sleep_cycle": 6600,
            "sleep_cycle_time": [
                "2023-01-01T16:43:03+00:00",
                "2023-01-01T17:47:03+00:00",
                "2023-01-01T19:24:33+00:00",
                "2023-01-01T20:38:33+00:00",
                "2023-01-01T21:55:33+00:00"
            ],
            "unstable_breath_count": 20,
            "snoring_count": 11
        }
    }
}

2.2 400 Bad Request

timezone didn't come in correctly

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

x-user-id: invalid format

{
	"detail": "The format of x-user-id is invalid"
}

session_id: invalid format

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

2.3 404 Not Found

session_idif the corresponding session is not found

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