특정 세션의 수면 분석 데이터를 요청합니다.

v4는 v3 응답에 더해, 분석 구간 정보를 담은 analysis 객체를 제공합니다. 분석 구간은 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		발급받은 user id
timezone	String	X	UTC	분석 결과의 시간대를 해당 timezone으로 변경해서 반환 예. UTC, Asia/Seoul

Path parameter

Field	Type	Required	Description
session_id	String	O	데이터를 요청하고자 하는 세션의 id

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

세션 상세 정보 조회 성공

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

세션의 상태와 계약 조건에 따라 stat object의 nullable이 결정됩니다.

if peculiarities == TOO_SHORT_FOR_ANALYSIS or TOO_MANY_DEFECTS_INSLEEP_STAGES: 무효 세션
- 그 이외의 모든 수면 분석이 진행된 세션은 유효 세션입니다.
if peculiarities == IN_PROGRESS or TOO_SHORT_FOR_ANALYSIS or TOO_MANY_DEFECTS_IN_SLEEP_STAGES: stat object는 null

Field	Type	Description
timezone	String	타임존 (Timezone List)
peculiarities	List	해당 수면 세션의 특이사항이 있을 경우 이를 설명해주는 필드. 해당 필드는 여러 개의 라벨을 포함할 수 있음. `IN_PROGRESS`: 세션이 OPEN, CLOSED인 경우 `FAILED`: 수면 분석에 실패한 경우 `NEVER_SLEPT`: 분석 결과 세션 측정시간 동안 전혀 잠을 자지 않았다고 판단 되는 경우 `TOO_SHORT_FOR_ANALYSIS`: 측정시간이 너무 짧아 유효한 분석을 할 수 없는 경우 (5분 미만) `TOO_LONG_FOR_ANALYSIS`: 분석은 정상적으로 되었지만, 세션 측정 시간이 너무 길어 신뢰하기 어려운 경우 (24시간 초과) `TOO_MANY_DEFECTS_IN_SLEEP_STAGES`: 오디오 업로드 누락 등의 이유로 오류율이 높아 수면 분석 결과가 충분하지 않은 경우 `NO_BREATHING_STABILITY`: Breathing_stability에 대한 분석은 더 이상 B2B로 제공하지 않아 V3 기준 모든 세션에 해당 peculiarities가 존재합니다. 향후 삭제할 예정입니다.
missing_data_ratio	float(`0~1 범위 소수점 둘째자리`)	오디오 업로드 누락 등의 이유로 인한 수면 분석 결과 오류율
session	Session Object	세션 분석 정보
stat	Stat Object?	분석 통계 정보
analysis	Analysis Object?	분석 구간 정보 분석 구간이 지정되지 않은 세션은 null

Session Object

if state == OPEN: session_end_time은 null
분석 구간이 지정된 세션(analysis가 null이 아닌 세션)의 경우, sleep_stages, breath_stages, snoring_stages 배열은 분석 구간 기준으로 반환됩니다.

분석 구간이 지정된 세션에서는 start_time/end_time이 분석 구간을 반영하며, 실제 측정 구간은 measurement_start_time/measurement_end_time에서 확인할 수 있습니다.

Field	Type	Description
id	String	session id
state	String (`OPEN`,`CLOSED`,`COMPLETE`)	세션의 상태 `OPEN`: 진행 중인 세션으로, 오디오 업로드가 가능한 상태 `CLOSED`: 세션 종료 요청이 보내져 종료된 세션. 오디오 파일 업로드 불가능. 업로드된 수면 오디오에 대한 분석이 계속 진행중인 상태 `COMPLETE`: 세션 종료 후 모든 수면 분석이 완료된 상태
start_time	String (`YYYY-MM-DDThh:mm:ss+-hh:mm`)	세션 시작 시각 예) 2022-08-01T01:31:17+09:00 (요청 타임존이 Asia/Seoul 일 경우)
end_time	String (`YYYY-MM-DDThh:mm:ss+-hh:mm`)?	세션 종료 시각 예) 2022-08-01T01:31:17+09:00 (요청 타임존이 Asia/Seoul 일 경우)
measurement_start_time	String (`YYYY-MM-DDThh:mm:ss+-hh:mm`)	실제 측정이 시작된 시각. 분석 구간(analysis range) 지정 여부와 무관한 원본 측정 구간이며, 요청 timezone이 적용됩니다.
measurement_end_time	String (`YYYY-MM-DDThh:mm:ss+-hh:mm`)?	실제 측정이 종료된 시각. 세션이 아직 종료되지 않았으면 null입니다. 요청 timezone이 적용됩니다.
unexpected_end_time	String (`YYYY-MM-DDThh:mm:ss+-hh:mm`)?	비정상 세션 종료 시각. 앱 크래시 등으로 세션이 정상적으로 진행 및 종료되지 못했을 경우, 나중에 클라이언트가 unexpected 파라미터를 1로 하여 세션을 종료시킬 경우 해당 시간이 기록됨. 이 경우 end_time은 마지막까지 업로드된 오디오 파일의 순서 번호를 기준으로 계산됨. 따라서 null이 아닐 경우 비정상 세션.
created_timezone	String	세션이 생성된 타임존 (Timezone List)
sleep_stages	[Sleep Stages]?	수면 단계 리스트
breath_stages	List of Int?	호흡 안정성 단계 리스트. 숫자 하나는 30초 구간의 호흡 안정/불안정 정도를 나타냄 `0`: 안정 `1`, `2`: 불안정 정도 (값이 클수록 불안정)
snoring_stages	[Snoring Stages]?	코골이 단계 리스트

Sleep Stages

sleep stage (수면 단계)는 -1,0,1,2,3 중 하나의 정수로 표현되며 숫자 하나는 30초 구간의 수면 단계를 나타냅니다. 각 숫자의 의미는 아래 표와 같습니다

계약 조건이 수면 단계 2레벨인 경우에는 0 (wake), 1 (sleep)

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 (코골이 단계)는 -1,0,1 중 하나의 정수로 표현되며 숫자 하나는 30초 구간의 코골이 단계를 나타냅니다. 각 숫자의 의미는 아래 표와 같습니다

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

Stat Object

각 메트릭에 대한 자세한 설명은 Key Concepts을 참조하실 수 있습니다.

if state == COMPLETE일 때
- if 2단계 수면 분석을 사용할 경우: wake와 sleep 밖에 단계가 없으므로 time_in_rem, time_in_light, time_in_deep, rem_ratio, light_ratio, deep_ratio, light_latency, deep_latency, rem_latency 값은 null
- if peculiarities == NEVER_SLEPT: 잠을 자지 않은 것이므로 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 모두 null
새롭게 추가된 메트릭들은 이전 세션들에 대한 데이터를 지원하지 않습니다.
- 메트릭 추가 시점은 https://docs.asleep.ai/changelog 에서 확인 가능합니다.

Field	Type	Description	Example
sleep_time	String (`YYYY-MM-DDThh:mm:ss+-hh:mm`)?	수면 측정 시작 후 잠들기 까지 걸린 시간	2022-08-01T00:30:00+09:00
wake_time	String (`YYYY-MM-DDThh:mm:ss+-hh:mm`)?	잠에서 깨어난 시각	2022-08-01T07:30:00+09:00
sleep_index	int(`50 <= sleep_index <= 100`)?	(Beta) 테스트 운영 수면 데이터	87
sleep_latency	Int (`seconds`)?	잠들때까지 걸린 시각	1800
wakeup_latency	Int (`seconds`)?	잠에서 깨어난 후 수면 측정을 종료하기까지 걸린 시간	1800
light_latency	Int(`seconds`)?	첫 수면 시작으로부터 첫 번째 light가 발생하기까지의 시간	300
deep_latency	Int(`seconds`)?	첫 수면 시작으로부터 첫 번째 deep이 발생하기까지의 시	600
rem_latency	Int(`seconds`)?	첫 수면 시작으로부터 첫 번째 rem이 발생하기까지의 시간	900
time_in_bed	Int (`seconds`)	수면 측정 시작 시각부터 수면 측정 종료 시각 까지의 시간	28800
time_in_sleep_period	Int (`seconds`)	수면 측정 시간 중 수면 측정 시작으로부터 잠들기 까지 걸린 시간과 잠에서 깨어난 후로부터 수면 측정을 종료하기까지 걸린 시간을 제외한 시간 (time_in_bed - sleep_latency - wakeup_latency)	27000
time_in_sleep	Int (`seconds`)	수면 측정 시간 중 실제로 수면 중이었던 시간 이 시간이 deep, light, rem의 3단계로 구분됨	24300
time_in_wake	Int (`seconds`)	수면 도중에 깬 시간	2700
time_in_light	Int (`seconds`)?	수면 단계가 light 로 진행된 총 시간	5400
time_in_deep	Int (`seconds`)?	수면 단계가 deep로 진행된 총 시간	5400
time_in_rem	Int (`seconds`)?	수면 단계가 rem 으로 진행된 총 시간	13500
time_in_stable_breath	Int (`seconds`)?	호흡이 안정 상태였던 총 시간	21600
time_in_unstable_breath	Int (`seconds`)?	호흡이 불안정 상태였던 총 시간	1800
time_in_snoring	Int?	코골이가 발생한 총 시간	5400
time_in_no_snoring	Int?	코골이가 발생하지 않은 총 시간	23400
sleep_efficiency	float (`0~1 범위 소수점 둘째자리`)	수면 측정 시간 중 실제로 잠든 시간의 비율	0.84
sleep_ratio	float (`0~1 범위 소수점 둘째자리`)?	수면 단계 도중 깨지 않고 잔 시간의 비율	0.9
wake_ratio	float (`0~1 범위 소수점 둘째자리`)?	수면 단계 도중 중간에 깬 시간의 비율	0.1
light_ratio	float (`0~1 범위 소수점 둘째자리`)?	수면 단계 도중 light 수면의 비율	0.2
deep_ratio	float (`0~1 범위 소수점 둘째자리`)?	수면 단계 도중 deep 수면의 비율	0.2
rem_ratio	float (`0~1 범위 소수점 둘째자리`)?	rem sleep 비율	0.5
stable_breath_ratio	float (`0~1 범위 소수점 둘째자리`)?	수면 구간 중 호흡이 안정 상태였던 시간의 비율	0.92
unstable_breath_ratio	float (`0~1 범위 소수점 둘째자리`)?	수면 구간 중 호흡이 불안정 상태였던 시간의 비율	0.08
snoring_ratio	float (`0~1 범위 소수점 둘째자리`)?	수면 단계 도중 코골이었던 시간의 비율	0.3
no_snoring_ratio	float (`0~1 범위 소수점 둘째자리`)?	수면 단계 도중 코골이가 아니었던 시간의 비율	0.7
breathing_index	float?	호흡 불안정 정도를 나타내는 지수	3.2
breathing_pattern	String (`STABLE_BREATH`, `MILDLY_UNSTABLE_BREATH`, `MODERATELY_UNSTABLE_BREATH`, `SEVERELY_UNSTABLE_BREATH`)?	호흡 안정성 패턴 `STABLE_BREATH`: 안정 호흡 `MILDLY_UNSTABLE_BREATH`: 경도 불안정 호흡 `MODERATELY_UNSTABLE_BREATH`: 중등도 불안정 호흡 `SEVERELY_UNSTABLE_BREATH`: 중증 불안정 호흡	STABLE_BREATH
waso_count	Int?	수면 구간 중 wake가 발생한 횟수	10
longest_waso	Int(`seconds`)?	수면 구간 중 가장 긴 wake의 시간	300
sleep_cycle_count	Int?	수면 주기의 횟수	4
sleep_cycle	Int(`seconds`)?	수면 주기 1회당 평균 시간	6600
sleep_cycle_time	List of String(`YYYY-MM-DDThh:mm:ss+-hh:mm`)	수면 주기 전환 기준 시각 예) [첫번째 수면 주기 시작 시각, 첫번째 수면 주기 종료 시각, 두번째 수면 주기 종료 시각, ..., 마지막 수면 주기 종료 시각]	["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?	불안정 호흡 구간이 발생한 횟수	5
snoring_count	Int?	코골이 구간이 발생한 횟수	11

Analysis Object

분석 구간이 지정된 세션에서만 반환되며, 세션 전체 중 어느 구간이 분석되었는지를 나타냅니다.

Field	Type	Description
start_epoch_index	Int	분석 구간의 시작 epoch 인덱스 (세션 전체 epoch 기준)
end_epoch_index	Int	분석 구간의 끝 epoch 인덱스 (exclusive, 해당 인덱스는 구간에 포함되지 않음)
epoch_durations	List of Int	각 epoch의 길이(초) 리스트
total_epoch_count	Int	세션 전체의 epoch 개수

400 Bad Request

timezone 이 잘못 들어온 경우

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

x-user-id가 잘못된 경우

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

session_id가 잘못된 형식인 경우

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

403 Forbidden

접근 권한이 없는 고객이 요청한 경우

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

404 Not Found

session_id에 해당되는 세션을 찾지 못한 경우

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