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

1. Request

1.1 URL

GET https://api.asleep.ai/data/v2/sessions/{session_id}

1.2 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

1.3 Path parameter

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

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

세션 상세 정보 조회 성공

2.1.1 Body (result field)

세션의 상태와 계약 조건에 따라 object와 object 내부 구성 요소들의 nullable이 결정됩니다.

if state != COMPLETE: stat object는 null
if state == COMPLETE && validity != VALID: stat object는 null

Field	Type	Description
timezone	String	타임존
validity	String	해당 수면 세션의 분석이 유효한지 여부 업로드된 오디오 파일들 일부가 유효하지 않거나, 유실된 비율이 일정 이상일 경우 분석이 부정확하여 이를 표시해주는 필드 `IN_PROGRESS`: 세션이 OPEN인 경우 `INVALID:TOO_MANDY_DEFECTS_IN_SLEEP_STAGES`: 수면 단계 분석 결과가 충분하지 않음 `INVALID:TOO_MANY_DEFECTS_IN_OSA_STAGES`: 호흡 안정도 분석 결과가 충분하지 않음 `VALID`: 분석이 유효
session	Session Object	세션 분석 정보
stat	Stat Object?	분석 통계 정보

2.1.2 Session Object

if state == OPEN: session_end_time은 null
- if 실시간 분석 사용 안할 경우: sleep_stages는 null
- if 호흡 안정도 분석 사용 안할 경우: osa_stages는 null
if state != OPEN
- if 호흡 안정도 분석 사용 안할 경우: osa_stages는 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 일 경우)
sleep_stages	[Sleep Stages]?	수면 단계 리스트
osa_stages	[OSA Stages]?	호흡 안정도 단계 리스트

2.1.3 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

2.1.4 OSA Stages

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

number	osa stage
-1	error (invalid audio, analysis error, etc)
0	stable
1	unstable

2.1.5 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 값은 null
- if 호흡 안정도 분석 사용 안할 경우: 해당 기능이 제공되지 않으므로 time_in_stable_breath, time_in_unstable_breath, stable_breath_ratio, unstable_breath_ratio, breathing_pattern, estimated_ahi 값은 null
- if 모든 stage가 wake인 경우(never slept session): 잠을 자지 않은 것이므로 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, estimated_ahi 모두 null

Field	Type	Description	Example
sleep_efficiency	float (`0~1 범위 소수점 둘째자리`)	수면 측정 시간 중 실제로 잠든 시간의 비율	0.84
sleep_latency	int (`seconds`)?	잠들때까지 걸린 시각	1800
sleep_time	String (`YYYY-MM-DDThh:mm:ss+-hh:mm`)?	수면 측정 시작 후 잠들기 까지 걸린 시간	2022-08-01T00:30:00+09:00
wakeup_latency	int (`seconds`)?	잠에서 깨어난 후 수면 측정을 종료하기까지 걸린 시간	1800
wake_time	String (`YYYY-MM-DDThh:mm:ss+-hh:mm`)?	잠에서 깨어난 시각	2022-08-01T07:30:00+09:00
time_in_wake	int (`seconds`)	수면 도중에 깬 시간	2700
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_bed	int (`seconds`)	수면 측정 시작 시각부터 수면 측정 종료 시각 까지의 시간	28800
time_in_rem	int (`seconds`)?	수면 단계가 rem 으로 진행된 총 시간	13500
time_in_light	int (`seconds`)?	수면 단계가 light 로 진행된 총 시간	5400
time_in_deep	int (`seconds`)?	수면 단계가 deep로 진행된 총 시간	5400
time_in_stable_breath	int (`seconds`)?	호흡 안정 구간이었던 총 시간	24300
time_in_unstable_breath	int (`seconds`)?	호흡 불안정 구간이었던 총 시간	2700
wake_ratio	float (`0~1 범위 소수점 둘째자리`)?	수면 단계 도중 중간에 깬 시간의 비율	0.1
sleep_ratio	float (`0~1 범위 소수점 둘째자리`)?	수면 단계 도중 깨지 않고 잔 시간의 비율	0.9
rem_ratio	float (`0~1 범위 소수점 둘째자리`)?	rem sleep 비율	0.5
light_ratio	float (`0~1 범위 소수점 둘째자리`)?	수면 단계 도중 light 수면의 비율	0.2
deep_ratio	float (`0~1 범위 소수점 둘째자리`)?	수면 단계 도중 deep 수면의 비율	0.2
stable_breath_ratio	float (`0~1 범위 소수점 둘째자리`)?	수면 단계 도중 호흡 안정 구간이었던 시간의 비율	0.9
unstable_breath_ratio	float (`0~1 범위 소수점 둘째자리`)?	수면 단계 도중 호흡 불안정 구간이었던 시간의 비율	0.1
breathing_pattern	String (`VERY_STABLE`,`STABLE`,`UNSTABLE`, `VERY_UNSTABLE`)?	호흡 불안정의 단계 `VERY_STABLE`: 매우 안정 `STABLE`: 안정 `UNSTABLE`: 불안정 `VERY_UNSTABLE`: 매우 불안정	STABLE
estimated_ahi	float (`0~1 범위 소수점 둘째자리`)?	호흡 불안정 레벨을 판단하기 위한 값	29.7

🚧
의료기기법 안내
서비스 화면 및 마케팅 자료에 수면 무호흡증, 무호흡, 저호흡, AHI 등의 질환 관련 명칭을 사용하면 의료기기법 위반으로 처분될 수 있어, 에이슬립에서는 '호흡 불안정'으로 표시하고 있습니다. 의료기기법 관련한 자세한 내용은 식약처에 문의하십시오.

{
  "detail": "ok",
  "result": {
    "timezone": "UTC",
    "validity": "VALID",
    "session": {
      "id": "20220821093117_hz82a",
      "state": "COMPLETE",
      "start_time": "2022-08-21T09:31:17+00:00",
      "end_time": "2022-08-21T09:56:17+00:00",
      "sleep_stages": [
        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1
      ],
      "osa_stages": [
        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
      ]
    },
    "stat": {
      "sleep_efficiency": 0.8,
      "sleep_latency": 300,
      "sleep_time": "2022-08-21T09:31:17+00:00",
      "wakeup_latency": 0,
      "wake_time": "2022-08-21T09:31:17+00:00",
      "time_in_wake": 0,
      "time_in_sleep": 1200,
      "time_in_bed": 1500,
      "time_in_sleep_period": 1200,
      "time_in_rem": 0,
      "time_in_light": 1200,
      "time_in_deep": 0,
      "time_in_stable_breath": 1200,
      "time_in_unstable_breath": 0,
      "wake_ratio": 0.0,
      "sleep_ratio": 1.0,
      "rem_ratio": 0.0,
      "light_ratio": 0.0,
      "deep_ratio": 0.0,
      "stable_breath_ratio": 1.0,
      "unstable_breath_ratio": 0.0,
      "breathing_pattern": "VERY_STABLE",
      "estimated_ahi": 0.0
    }
  }
}

2.2 400 Bad Request

timezone 이 잘못 들어온 경우

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

2.3 404 Not Found

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

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

2.4 422 Unprocessable Entity

session_id가 유효하지 않은 경우

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