You can check the average sleep metrics for a specific period of time. Currently, you can retrieve data for up to 100 days.

1. Request

1.1 URL

GET https://api.asleep.ai/data/v1/users/{user_id}/average-stats

1.2 Header

Field	Type	Required	Default	Description
x-api-key	String	O	-	API Key
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
user_id	String	O	id of the session in which you want to request data

1.4 Query string

Field	Type	Required	Default	Description
start_date	String	O	-	The starting time for the period you want to check the average
end_date	String	O	-	The ending time for the period you want to check the average

Example

curl "https://api.asleep.ai/data/v1/users/{user_id}/average-stats?start_date=2023-10-20&end_date=2023-10-30" -XGET \
  -H "x-api-key: <YOUR_API_KEY>"

2. Response

2.1 200 OK

조회 성공

2.1.1 Body (result field)

Field	Type	Description
period	Period Object	Timezone (Timezone List)
peculiarities	List	Special considerations when calculating the average of sleep sessions `NO_BREATHING_STABILITY`: When the customer's contract conditions do not support breathing stability analysis
average_stats	Average Stats Object?	An object containing the averages of sleep metrics for "slept_sessions"
never_slept_sessions	List of Never Slept Session Object	A list of sessions during which it is determined that no sleep occurred at all during the measurement time.
slept_sessions	List of Slept Session Object	A list of sessions during which it is determined that sleep occurred during the measurement time.

2.1.2 Period Object

Field	Type	Description
timezone	String	requested timezone 예. UTC, Asia/Seoul
start_date	String(`YYYY-MM-DD`)	requested start date
end_date	String (`YYYY-MM-DD`)	requested end date

2.1.3 Average Stats Object

Field	Type	Description
start_time	String(`hh:mm:ss`)	Session start time
end_time	String(`hh:mm:ss`)	Session end time
sleep_time	String (`hh:mm:ss`)	The time it takes to fall asleep after the start of sleep staging
wake_time	String (`hh:mm:ss`)	Wake time
sleep_latency	Int	Time to fall asleep
wakeup_latency	Int	The time it takes to wake up and end your sleep measurement
time_in_bed	Int	The time from the start of the sleep measurement to the end of the sleep measurement
time_in_sleep_period	Int	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)
time_in_sleep	Int	During sleep measurement time, the time you were actually sleeping This time is divided into three stages: deep,light,and rem
time_in_wake	Int	Wake time during sleep
time_in_light	Int?	Total time the sleep phase progressed to light
time_in_deep	Int?	Total time the sleep phase progressed to deep
time_in_rem	Int?	Total time the sleep phase progressed to rem
time_in_stable_breath	Int?	Total time in the breathing stable section
time_in_unstable_breath	Int?	Total time of breath instability
time_in_snoring	Int?	Total time of snoring
time_in_no_snoring	Int?	Total time of no snoring
sleep_efficiency	float(`0~1 range, decimal points`)	The percentage of time you actually slept during sleep measurement
wake_ratio	float(`0~1 range, decimal points`)	Rate of waking time in the middle during sleep phase
sleep_ratio	float(`0~1 range, decimal points`)	During sleep stage, sleep ratio, not wake
light_ratio	float(`0~1 range, decimal points`)?	Rate of light sleep during sleep phase
deep_ratio	float(`0~1 range, decimal points`)?	Rate of deep sleep during sleep phase
rem_ratio	float(`0~1 range, decimal points`)?	rem sleep ratio
stable_breath_ratio	float(`0~1 range, decimal points`)?	The percentage of time that was a breathing stable section during the sleep phase
unstable_breath_ratio	float(`0~1 range, decimal points`)?	The percentage of time during the sleep phase that there was a breathing instability section
snoring_ratio	float(`0~1 range, decimal points`)?	The percentage of time during the sleep phase that there was a snoring section
no_snoring_ratio	float(`0~1 range, decimal points`)?	The percentage of time during the sleep phase that there was no snoring.
breathing_index	float (0~1 range, decimal points)?	Values for determining respiratory instability levels
waso_count	Int?	The number of times 'wake' occurred during the sleep period
longest_waso	Int?	The duration of the longest 'wake' during the sleep period
unstable_breath_count	Int?	The number of times unstable breathing occurred.
sleep_cycle_count	Int?	The number of sleep cycles.
snoring_count	Int?	The number of times snoring occurred.

2.1.4 Never Slept Session Object

Field	Type	Description
id	String	session id
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)
completed_time	String(`YYYY-MM-DDThh:mm:ss+-hh:mm`)	Time of session analysis completion Example) 2022-08-01T01:31: 17+09: 00 (If the request timezone is Asia/Seoul)

2.1.5 Slept Session Object

Field	Type	Description
id	String	session id
created_timezone	String	Timezone of session creation (Timezone List)
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)
completed_time	String(`YYYY-MM-DDThh:mm:ss+-hh:mm`)	Time of session analysis completion Example) 2022-08-01T01:31: 17+09: 00 (If the request timezone is Asia/Seoul)
sleep_time	String (`YYYY-MM-DDThh:mm:ss+-hh:mm`)?	The time it takes to fall asleep after the start of sleep staging
wake_time	String (`YYYY-MM-DDThh:mm:ss+-hh:mm`)?	Wake time
sleep_latency	int (`seconds`)?	Time to fall asleep
wakeup_latency	int (`seconds`)?	The time it takes to wake up and end your sleep measurement
sleep_efficiency	float (`0~1 range, decimal points`)	The percentage of time you actually slept during sleep measurement
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
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)
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
time_in_wake	int (`seconds`)	Wake time during sleep
time_in_rem	int (`seconds`)?	Total time the sleep phase progressed to rem
time_in_light	int (`seconds`)?	Total time the sleep phase progressed to light
time_in_deep	int (`seconds`)?	Total time the sleep phase progressed to deep
time_in_stable_breath	int (`seconds`)?	Total time in the breathing stable section
time_in_unstable_breath	int (`seconds`)?	Total time of breath instability
time_in_snoring	int (`seconds`)?	Total time of snoring
time_in_no_snoring	int (`seconds`)?	Total time of no snoring
wake_ratio	float (`0~1 range, decimal points`)	Rate of waking time in the middle during sleep phase
sleep_ratio	float (`0~1 range, decimal points`)	During sleep stage, sleep ratio, not wake
light_ratio	float (`0~1 range, decimal points`)?	Rate of light sleep during sleep phase
deep_ratio	float (`0~1 range, decimal points`)?	Rate of deep sleep during sleep phase
rem_ratio	float (`0~1 range, decimal points`)?	rem sleep ratio
stable_breath_ratio	float (`0~1 range, decimal points`)?	The percentage of time that was a breathing stable section during the sleep phase
unstable_breath_ratio	float (`0~1 range, decimal points`)?	The percentage of time during the sleep phase that there was a breathing instability section
snoring_ratio	float (`0~1 range, decimal points`)?	The percentage of time during the sleep phase that there was a snoring section
no_snoring_ratio	float (`0~1 range, decimal points`)?	The percentage of time during the sleep phase that there was no snoring.
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
breathing_index
waso_count	int?	The number of times 'wake' occurred during the sleep period
longest_waso	int(`seconds`)?	The duration of the longest 'wake' during the sleep period
sleep_cycle_count	int?	The number of sleep cycles
sleep_cycle	int(`seconds`)?	The average duration of one sleep cycle
unstable_breath_count	Int?	The number of times unstable breathing occurred.
snoring_count	Int?	The number of times snoring occurred.

{
    "detail": "OK",
    "result": {
        "period": {
            "timezone": "UTC",
            "start_date": "2023-09-01",
            "end_date": "2023-09-05"
        },
        "peculiarities": [],
        "average_stats": {
            "start_time": "17:45:45",
            "end_time": "00:26:34",
            "sleep_time": "18:08:43",
            "wake_time": "00:26:03",
            "sleep_latency": 1230,
            "wakup_latency": 300,
            "time_in_bed": 24089,
            "time_in_sleep": 19238,
            "time_in_wake": 3428,
            "time_in_light": 11025,
            "time_in_deep": 1732,
            "time_in_rem": 6480,
            "time_in_stable_breath": 22418,
            "time_in_unstable_breath": 248,
            "time_in_snoring": 5400,
            "time_in_no_snoring": 23400,
            "sleep_efficiency": 0.8,
            "wake_ratio": 0.15,
            "sleep_ratio": 0.75,
            "light_ratio": 0.48,
            "deep_ratio": 0.08,
            "rem_ratio": 0.29,
            "stable_breath_ratio": 0.99,
            "unstable_breath_ratio": 0.01,
            "snoring_ratio": 0.3,
            "no_snoring_ratio": 0.7,
            "breathing_index": 64.83,
            "waso_count": 0,
            "longest_waso": 300,
            "unstable_breath_count": 1,
            "sleep_cycle_count": 4,
            "snoring_count": 11
        },
        "never_slept_sessions": [
            {
                "id": "20230905141915_5jxau",
                "start_time": "2023-09-05T14:19:15+00:00",
                "end_time": "2023-09-05T14:49:19+00:00",
                "completed_time": "2023-09-05T14:54:56+00:00"
            }
        ],
        "slept_sessions": [
            {
                "id": "20230903222612_ezu0o",
                "created_timezone": "UTC",
                "start_time": "2023-09-03T22:26:12+00:00",
                "end_time": "2023-09-04T05:21:36+00:00",
                "completed_time": "2023-09-04T05:28:34+00:00",
                "sleep_time": "2023-09-03T22:31:12+00:00",
                "wake_time": "2023-09-04T05:23:34+00:00",
                "sleep_latency": 300,
                "wakeup_latency": 0,
                "light_latency": 0,
                "deep_latency": 1680,
                "rem_latency": 2820,
                "time_in_bed": 24924,
                "time_in_sleep_period": 24600,
                "time_in_sleep": 24060,
                "time_in_wake": 540,
                "time_in_light": 11580,
                "time_in_deep": 3120,
                "time_in_rem": 9360,
                "time_in_stable_breath": 24300,
                "time_in_unstable_breath": 300,
                "time_in_snoring": 5400,
                "time_in_no_snoring": 23400,
                "sleep_efficiency": 0.97,
                "sleep_ratio": 0.98,
                "wake_ratio": 0.02,
                "light_ratio": 0.47,
                "deep_ratio": 0.13,
                "rem_ratio": 0.38,
                "stable_breath_ratio": 0.99,
                "unstable_breath_ratio": 0.01,
                "snoring_ratio": 0.3,
                "no_snoring_ratio": 0.7,
                "breathing_pattern": "STABLE_BREATH",
                "breathing_index": 64.83,
                "waso_count": 14,
                "longest_waso": 90,
                "sleep_cycle_count": 4,
                "sleep_cycle": 5475,
                "unstable_breath_count": 2,
                "snoring_count": 11
            },
            {
                "id": "20230904182412_g2mfo",
                "created_timezone": "UTC",
                "start_time": "2023-09-04T18:24:12+00:00",
                "end_time": "2023-09-05T01:29:30+00:00",
                "completed_time": "2023-09-05T01:34:38+00:00",
                "sleep_time": "2023-09-04T18:44:12+00:00",
                "wake_time": "2023-09-05T01:29:08+00:00",
                "sleep_latency": 1200,
                "wakeup_latency": 30,
                "light_latency": 0,
                "deep_latency": 1890,
                "rem_latency": 3240,
                "time_in_bed": 25518,
                "time_in_sleep_period": 24270,
                "time_in_sleep": 23640,
                "time_in_wake": 630,
                "time_in_light": 15210,
                "time_in_deep": 1920,
                "time_in_rem": 6510,
                "time_in_stable_breath": 24270,
                "time_in_unstable_breath": 0,
                "time_in_snoring": 5400,
                "time_in_no_snoring": 23400,
                "sleep_efficiency": 0.93,
                "sleep_ratio": 0.97,
                "wake_ratio": 0.03,
                "light_ratio": 0.62,
                "deep_ratio": 0.08,
                "rem_ratio": 0.27,
                "stable_breath_ratio": 1.0,
                "unstable_breath_ratio": 0.0,
                "snoring_ratio": 0.3,
                "no_snoring_ratio": 0.7,
                "breathing_pattern": "STABLE_BREATH",
                "breathing_index": 64.83,
                "waso_count": 17,
                "longest_waso": 60,
                "sleep_cycle_count": 4,
                "sleep_cycle": 5925,
                "unstable_breath_count": 0,
                "snoring_count": 11
            },
            {
                "id": "20230730233635_fx2s1",
                "created_timezone": "UTC",
                "start_time": "2023-09-05T15:38:00+00:00",
                "end_time": "2023-09-05T21:32:51+00:00",
                "completed_time": "2023-09-05T21:37:51+00:00",
                "sleep_time": "2023-09-05T16:15:00+00:00",
                "wake_time": "2023-09-05T21:32:51+00:00",
                "sleep_latency": 2220,
                "wakeup_latency": 0,
                "light_latency": 0,
                "deep_latency": 480,
                "rem_latency": 3180,
                "time_in_bed": 21291,
                "time_in_sleep_period": 18780,
                "time_in_sleep": 17790,
                "time_in_wake": 990,
                "time_in_light": 9990,
                "time_in_deep": 1890,
                "time_in_rem": 5910,
                "time_in_stable_breath": 18090,
                "time_in_unstable_breath": 690,
                "time_in_snoring": 5400,
                "time_in_no_snoring": 23400,
                "sleep_efficiency": 0.84,
                "sleep_ratio": 0.95,
                "wake_ratio": 0.05,
                "light_ratio": 0.54,
                "deep_ratio": 0.1,
                "rem_ratio": 0.31,
                "stable_breath_ratio": 0.96,
                "unstable_breath_ratio": 0.04,
                "snoring_ratio": 0.3,
                "no_snoring_ratio": 0.7,
                "breathing_pattern": "STABLE_BREATH",
                "breahting_index": 64.83,
                "waso_count": 19,
                "longest_waso": 240,
                "sleep_cycle_count": 2,
                "sleep_cycle": 7515,
                "unstable_breath_count": 2,
                "snoring_count": 11
            },
            {
                "id": "20230905152426_wjvfy",
                "created_timezone": "UTC",
                "start_time": "2023-09-05T15:24:26+00:00",
                "end_time": "2023-09-05T22:14:48+00:00",
                "completed_time": "2023-09-05T22:24:21+00:00",
                "sleep_time": "2023-09-05T15:44:26+00:00",
                "wake_time": "2023-09-05T22:12:51+00:00",
                "sleep_latency": 1200,
                "wakeup_latency": 390,
                "light_latency": 0,
                "deep_latency": null,
                "rem_latency": 4440,
                "time_in_bed": 24622,
                "time_in_sleep_period": 23010,
                "time_in_sleep": 11460,
                "time_in_wake": 11550,
                "time_in_light": 7320,
                "time_in_deep": 0,
                "time_in_rem": 4140,
                "time_in_stable_breath": 23010,
                "time_in_unstable_breath": 0,
                "time_in_snoring": 5400,
                "time_in_no_snoring": 23400,
                "sleep_efficiency": 0.47,
                "sleep_ratio": 0.5,
                "wake_ratio": 0.5,
                "light_ratio": 0.32,
                "deep_ratio": 0.0,
                "rem_ratio": 0.18,
                "stable_breath_ratio": 1.0,
                "unstable_breath_ratio": 0.0,
                "snoring_ratio": 0.7,
                "no_snoring_ratio": 0.3,
                "breathing_pattern": "STABLE_BREATH",
                "waso_count": 20,
                "longest_waso": 3180,
                "sleep_cycle_count": 3,
                "sleep_cycle": 6700,
                "unstable_breath_count": 0,
                "snoring_count": 11
            }
        ]
    }
}

2.2 400 Bad Request

If the requested period exceeds the available range or if the date format of the start_date or end_date is incorrect

{
	"detail": "The period should be less than or equal to 100 days"
}

2.3 404 Not Found

if the corresponding user_id is not found

{
	"detail": "Unable to find the user of id {user_id}"
}