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

Request

URL

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

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

Path parameter

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

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

Response

200 OK

Success

{
    "detail": "OK",
    "result": {
        "period": {
            "timezone": "UTC",
            "start_date": "2025-01-01",
            "end_date": "2025-01-05"
        },
        "peculiarities": ["NO_BREATHING_STABILITY"],
        "average_stats": {
            "start_time": "02:54:01",
            "end_time": "07:28:03",
            "sleep_time": "03:10:30",
            "wake_time": "07:17:44",
            "sleep_latency": 990,
            "wakeup_latency": 714,
            "time_in_bed": 16381,
            "time_in_sleep_period": 14658,
            "time_in_sleep": 14154,
            "time_in_wake": 504,
            "time_in_light": 6492,
            "time_in_deep": 3270,
            "time_in_rem": 4392,
            "time_in_stable_breath": null,
            "time_in_unstable_breath": null,
            "time_in_snoring": 53,
            "time_in_no_snoring": 18270,
            "sleep_efficiency": 0.864,
            "wake_ratio": 0.034,
            "sleep_ratio": 0.966,
            "light_ratio": 0.443,
            "deep_ratio": 0.223,
            "rem_ratio": 0.3,
            "stable_breath_ratio": null,
            "unstable_breath_ratio": null,
            "snoring_ratio": 0.004,
            "no_snoring_ratio": 0.996,
            "breathing_index": null,
            "waso_count": 7,
            "longest_waso": 228,
            "unstable_breath_count": null,
            "sleep_cycle_count": 3,
            "snoring_count": 2
        },
        "never_slept_sessions": [],
        "slept_sessions": [
            {
                "id": "20250101173000_biuw0",
                "created_timezone": "Asia/Seoul",
                "start_time": "2025-01-01T17:30:00+00:00",
                "end_time": "2025-01-01T22:37:23+00:00",
                "completed_time": "2025-01-01T22:37:25+00:00",
                "sleep_time": "2025-01-01T17:30:00+00:00",
                "wake_time": "2025-01-01T22:32:23+00:00",
                "sleep_latency": 0,
                "wakeup_latency": 300,
                "light_latency": 0,
                "deep_latency": 390,
                "rem_latency": 3840,
                "time_in_bed": 18443,
                "time_in_sleep_period": 18120,
                "time_in_sleep": 17910,
                "time_in_wake": 210,
                "time_in_light": 7020,
                "time_in_deep": 4410,
                "time_in_rem": 6480,
                "time_in_stable_breath": null,
                "time_in_unstable_breath": null,
                "time_in_snoring": 60,
                "time_in_no_snoring": 18060,
                "sleep_efficiency": 0.97,
                "sleep_ratio": 0.99,
                "wake_ratio": 0.01,
                "light_ratio": 0.39,
                "deep_ratio": 0.24,
                "rem_ratio": 0.36,
                "stable_breath_ratio": null,
                "unstable_breath_ratio": null,
                "snoring_ratio": 0.0,
                "no_snoring_ratio": 1.0,
                "breathing_pattern": null,
                "breathing_index": null,
                "waso_count": 7,
                "longest_waso": 30,
                "sleep_cycle_count": 4,
                "sleep_cycle": 4522,
                "unstable_breath_count": null,
                "snoring_count": 2
            },
            {
                "id": "20250102180002_1it7v",
                "created_timezone": "Asia/Seoul",
                "start_time": "2025-01-02T18:00:02+00:00",
                "end_time": "2025-01-02T23:05:06+00:00",
                "completed_time": "2025-01-02T23:05:07+00:00",
                "sleep_time": "2025-01-02T18:30:02+00:00",
                "wake_time": "2025-01-02T23:05:06+00:00",
                "sleep_latency": 1800,
                "wakeup_latency": 0,
                "light_latency": 0,
                "deep_latency": 510,
                "rem_latency": 3750,
                "time_in_bed": 18304,
                "time_in_sleep_period": 16500,
                "time_in_sleep": 15660,
                "time_in_wake": 840,
                "time_in_light": 8460,
                "time_in_deep": 3690,
                "time_in_rem": 3510,
                "time_in_stable_breath": null,
                "time_in_unstable_breath": null,
                "time_in_snoring": 30,
                "time_in_no_snoring": 16470,
                "sleep_efficiency": 0.86,
                "sleep_ratio": 0.95,
                "wake_ratio": 0.05,
                "light_ratio": 0.52,
                "deep_ratio": 0.22,
                "rem_ratio": 0.21,
                "stable_breath_ratio": null,
                "unstable_breath_ratio": null,
                "snoring_ratio": 0.0,
                "no_snoring_ratio": 1.0,
                "breathing_pattern": null,
                "breathing_index": null,
                "waso_count": 10,
                "longest_waso": 240,
                "sleep_cycle_count": 3,
                "sleep_cycle": 5490,
                "unstable_breath_count": null,
                "snoring_count": 1
            },
            {
                "id": "20250103180002_91khj",
                "created_timezone": "Asia/Seoul",
                "start_time": "2025-01-03T18:00:02+00:00",
                "end_time": "2025-01-03T23:05:14+00:00",
                "completed_time": "2025-01-03T23:05:15+00:00",
                "sleep_time": "2025-01-03T18:00:02+00:00",
                "wake_time": "2025-01-03T23:05:14+00:00",
                "sleep_latency": 0,
                "wakeup_latency": 0,
                "light_latency": 0,
                "deep_latency": 390,
                "rem_latency": 3360,
                "time_in_bed": 18312,
                "time_in_sleep_period": 18300,
                "time_in_sleep": 17220,
                "time_in_wake": 1080,
                "time_in_light": 8910,
                "time_in_deep": 3150,
                "time_in_rem": 5160,
                "time_in_stable_breath": null,
                "time_in_unstable_breath": null,
                "time_in_snoring": 0,
                "time_in_no_snoring": 18300,
                "sleep_efficiency": 0.94,
                "sleep_ratio": 0.94,
                "wake_ratio": 0.06,
                "light_ratio": 0.49,
                "deep_ratio": 0.17,
                "rem_ratio": 0.28,
                "stable_breath_ratio": null,
                "unstable_breath_ratio": null,
                "snoring_ratio": 0.0,
                "no_snoring_ratio": 1.0,
                "breathing_pattern": null,
                "breathing_index": null,
                "waso_count": 8,
                "longest_waso": 720,
                "sleep_cycle_count": 3,
                "sleep_cycle": 5940,
                "unstable_breath_count": null,
                "snoring_count": 0
            },
            {
                "id": "20250104180001_z8tn9",
                "created_timezone": "Asia/Seoul",
                "start_time": "2025-01-04T18:00:01+00:00",
                "end_time": "2025-01-04T20:27:03+00:00",
                "completed_time": "2025-01-04T20:27:05+00:00",
                "sleep_time": "2025-01-04T18:00:01+00:00",
                "wake_time": "2025-01-04T19:32:33+00:00",
                "sleep_latency": 0,
                "wakeup_latency": 3270,
                "light_latency": 0,
                "deep_latency": 690,
                "rem_latency": 3630,
                "time_in_bed": 8822,
                "time_in_sleep_period": 5520,
                "time_in_sleep": 5370,
                "time_in_wake": 150,
                "time_in_light": 2100,
                "time_in_deep": 1680,
                "time_in_rem": 1590,
                "time_in_stable_breath": null,
                "time_in_unstable_breath": null,
                "time_in_snoring": 30,
                "time_in_no_snoring": 5490,
                "sleep_efficiency": 0.61,
                "sleep_ratio": 0.97,
                "wake_ratio": 0.03,
                "light_ratio": 0.38,
                "deep_ratio": 0.3,
                "rem_ratio": 0.29,
                "stable_breath_ratio": null,
                "unstable_breath_ratio": null,
                "snoring_ratio": 0.01,
                "no_snoring_ratio": 0.99,
                "breathing_pattern": null,
                "breathing_index": null,
                "waso_count": 3,
                "longest_waso": 60,
                "sleep_cycle_count": 1,
                "sleep_cycle": 5190,
                "unstable_breath_count": null,
                "snoring_count": 1
            },
            {
                "id": "20250105180002_s3dh3",
                "created_timezone": "Asia/Seoul",
                "start_time": "2025-01-05T18:00:02+00:00",
                "end_time": "2025-01-05T23:00:26+00:00",
                "completed_time": "2025-01-05T23:00:27+00:00",
                "sleep_time": "2025-01-05T18:52:32+00:00",
                "wake_time": "2025-01-05T23:00:26+00:00",
                "sleep_latency": 3150,
                "wakeup_latency": 0,
                "light_latency": 0,
                "deep_latency": 450,
                "rem_latency": 3750,
                "time_in_bed": 18024,
                "time_in_sleep_period": 14850,
                "time_in_sleep": 14610,
                "time_in_wake": 240,
                "time_in_light": 5970,
                "time_in_deep": 3420,
                "time_in_rem": 5220,
                "time_in_stable_breath": null,
                "time_in_unstable_breath": null,
                "time_in_snoring": 90,
                "time_in_no_snoring": 14760,
                "sleep_efficiency": 0.81,
                "sleep_ratio": 0.98,
                "wake_ratio": 0.02,
                "light_ratio": 0.4,
                "deep_ratio": 0.23,
                "rem_ratio": 0.35,
                "stable_breath_ratio": null,
                "unstable_breath_ratio": null,
                "snoring_ratio": 0.01,
                "no_snoring_ratio": 0.99,
                "breathing_pattern": null,
                "breathing_index": null,
                "waso_count": 6,
                "longest_waso": 90,
                "sleep_cycle_count": 2,
                "sleep_cycle": 7155,
                "unstable_breath_count": null,
                "snoring_count": 3
            }
        ]
    }
}

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`: Analysis for breathing_stability is no longer provided in B2B services. As of V3, this peculiarities value exists in all sessions and is planned for removal in future updates.
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.

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

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_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
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.
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
sleep_cycle_count	Int?	The number of sleep cycles.
snoring_count	Int?	The number of times snoring occurred.

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)

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_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
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.
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
snoring_count	Int?	The number of times snoring occurred.

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

404 Not Found

if the corresponding user_id is not found

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