Request sleep analysis data for a specific session.

In addition to the v3 response, v4 provides an analysis object that describes the analysis range of the session. The analysis range can be set with Reanalyze Session.

Request

URL

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

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

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/v4/sessions/{session_id}" -XGET \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "x-user-id: <USER_ID>"

Response

200 OK

Session details lookup success

{
    "detail": "OK",
    "result": {
        "timezone": "UTC",
        "peculiarities": ["NO_BREATHING_STABILITY"],
        "missing_data_ratio": 0.0,
        "session": {
            "id": "20250115025029_fvivn",
            "state": "COMPLETE",
            "start_time": "2025-01-15T02:50:29+00:00",
            "end_time": "2025-01-15T03:50:29+00:00",
            "measurement_start_time": "2025-01-15T02:50:29+00:00",
            "measurement_end_time": "2025-01-15T03:50:29+00:00",
            "unexpected_end_time": null,
            "created_timezone": "UTC",
            "sleep_stages": [0], //omitted
            "breath_stages": null,
            "snoring_stages": [0] // omitted
        },
        "stat": {
            "sleep_time": "2025-01-15T03:05:29+00:00",
            "wake_time": "2025-01-15T03:26:29+00:00",
            "sleep_index": 50,
            "sleep_latency": 900,
            "wakeup_latency": 1440,
            "light_latency": 0,
            "deep_latency": null,
            "rem_latency": null,
            "time_in_bed": 3600,
            "time_in_sleep_period": 1260,
            "time_in_sleep": 1080,
            "time_in_wake": 180,
            "time_in_light": 1080,
            "time_in_deep": 0,
            "time_in_rem": 0,
            "time_in_stable_breath": null,
            "time_in_unstable_breath": null,
            "time_in_snoring": 0,
            "time_in_no_snoring": 1260,
            "sleep_efficiency": 0.3,
            "sleep_ratio": 0.86,
            "wake_ratio": 0.14,
            "light_ratio": 0.86,
            "deep_ratio": 0.0,
            "rem_ratio": 0.0,
            "stable_breath_ratio": null,
            "unstable_breath_ratio": null,
            "snoring_ratio": 0.0,
            "no_snoring_ratio": 1.0,
            "breathing_index": null,
            "breathing_pattern": null,
            "waso_count": 1,
            "longest_waso": 180,
            "sleep_cycle_count": 0,
            "sleep_cycle": null,
            "sleep_cycle_time": [],
            "unstable_breath_count": null,
            "snoring_count": 0
        },
        "analysis": {
            "start_epoch_index": 20,
            "end_epoch_index": 500,
            "epoch_durations": [30], //omitted
            "total_epoch_count": 720
        }
    }
}

Body (result field)

The nullability of thestat object is determined based on the session status and contract conditions.

Invalid session:
- if peculiarities == TOO_SHORT_FOR_ANALYSIS or TOO_MANY_DEFECTS_IN_SLEEP_STAGES
- All other sessions where sleep analysis has been conducted are considered valid sessions.
statobject isnull if :
- peculiarities == IN_PROGRESS or TOO_SHORT_FOR_ANALYSIS or TOO_MANY_DEFECTS_IN_SLEEP_STAGES

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 `FAILED`: If the sleep analysis has failed `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 5 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.
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
analysis	Analysis Object?	Analysis range information null for sessions without a specified analysis range

Session Object

if state == OPEN: session_end_time is null
For sessions with a specified analysis range (sessions whose analysis is not null), the sleep_stages, breath_stages, and snoring_stages arrays are returned based on the analysis range.

For sessions with an analysis range, start_time/end_time reflect the analysis range; the actual measurement window is available in measurement_start_time/measurement_end_time.

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)
measurement_start_time	String (`YYYY-MM-DDThh:mm:ss+-hh:mm`)	The time the actual measurement started. This is the original measurement window, unaffected by any analysis range, converted to the requested timezone.
measurement_end_time	String (`YYYY-MM-DDThh:mm:ss+-hh:mm`)?	The time the actual measurement ended. Null if the session has not ended yet. Converted to the requested timezone.
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	List of Int?	Breathing stability stages list. Each number represents the degree of breathing stability/instability for a 30-second interval `0`: stable `1`, `2`: unstable (a higher value means more unstable)
snoring_stages	[Snoring Stages]?	Snoring Stages List

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

Snoring Stages

snoring 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

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 == NEVER_SLEPT: didn't sleep: sleep_latency, sleep_time, wakeup_latency, wake_time, wake_ratio, sleep_ratio, rem_ratio, light_ratio, deep_ratio, 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-en.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 of stable breathing	21600
time_in_unstable_breath	Int (`seconds`)?	Total time of unstable breathing	1800
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 ratio of time with stable breathing during the sleep period	0.92
unstable_breath_ratio	float (`0~1 range, decimal points`)?	The ratio of time with unstable breathing during the sleep period	0.08
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?	Index representing the degree of breathing instability	3.2
breathing_pattern	String (`STABLE_BREATH`, `MILDLY_UNSTABLE_BREATH`, `MODERATELY_UNSTABLE_BREATH`, `SEVERELY_UNSTABLE_BREATH`)?	Breathing stability pattern `STABLE_BREATH`: stable breathing `MILDLY_UNSTABLE_BREATH`: mildly unstable breathing `MODERATELY_UNSTABLE_BREATH`: moderately unstable breathing `SEVERELY_UNSTABLE_BREATH`: severely unstable breathing	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 sections occurred	5
snoring_count	Int?	The number of times snoring occurred.

Analysis Object

Returned only for sessions with a specified analysis range. It describes which part of the whole session was analyzed.

Field	Type	Description
start_epoch_index	Int	Start epoch index of the analysis range (based on the epochs of the whole session)
end_epoch_index	Int	End epoch index of the analysis range (exclusive; this index is not included in the range)
epoch_durations	List of Int	List of the duration (seconds) of each epoch
total_epoch_count	Int	Total number of epochs in the whole session

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"
}

403 Forbidden

An inaccessible customer has made a request

{
	"detail": "An inaccessible customer has made a request"
}

404 Not Found

session_idif the corresponding session is not found

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