Get Single Session
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, CLOSEDNEVER_SLEPT : If it is determined that there was no sleep at all during the session measurement timeTOO_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 nullif peculiarities == NO_REALTIME_POLLING
: sleep_stages is nullif peculiarities == NO_BREATHING_STABILITY
: breath_stages is null
Field | Type | Description |
---|---|---|
id | String | session id |
state | String (OPEN ,CLOSED ,COMPLETE ) | Status of SessionOPEN : An in-progress session, with audio uploads availableCLOSED : The session terminated by sending an end session request. Unable to upload audio files. Analysis of uploaded sleep audio is still in progressCOMPLETE : 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 nullif 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 nullif 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 LevelSTABLE_BREATH : stableMILDLY_UNSTABLE_BREATH : mildly unstableMODERTATELY_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_id
if the corresponding session is not found
{
"detail": "Unable to find the sleep session of id {session_id}"
}
Updated 6 months ago