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

Request

URL

GET https://api.asleep.ai/data/v3/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/v3/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",
            "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
        }
    }
}

Body (result field)

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

if peculiarities == TOO_SHORT_FOR_ANALYSIS or TOO_MANY_DEFECTS_INSLEEP_STAGES: 무효 세션
- 그 이외의 모든 수면 분석이 진행된 세션은 유효 세션입니다.
if peculiarities == IN_PROGRESS or NO_REALTIME_POLLING 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인 경우 `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가 존재합니다. 향후 삭제할 예정입니다. `NO_REALTIME_POLLING`: 고객의 계약 조건상 실시간으로 수면 정보를 확인할 수 없는 경우
missing_data_ratio	float(`0~1 범위 소수점 둘째자리`)	오디오 업로드 누락 등의 이유로 인한 수면 분석 결과 오류율
session	Session Object	세션 분석 정보
stat	Stat Object?	분석 통계 정보

Session Object

if state == OPEN: session_end_time은 null

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 일 경우)
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]?	수면 단계 리스트
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_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
snoring_ratio	float (`0~1 범위 소수점 둘째자리`)?	수면 단계 도중 코골이었던 시간의 비율	0.3
no_snoring_ratio	float (`0~1 범위 소수점 둘째자리`)?	수면 단계 도중 코골이가 아니었던 시간의 비율	0.7
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"]
snoring_count	Int?	코골이 구간이 발생한 횟수	11

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

404 Not Found

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

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