Get Single Session

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

1. Request

1.1 URL

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

1.2 Header

FieldTypeRequiredDefaultDescription
x-api-keyStringO-API Key
x-user-idStringO-발급받은 user id
timezoneStringXUTC분석 결과의 시간대를 해당 timezone으로 변경해서 반환
예. UTC, Asia/Seoul

1.3 Path parameter

FieldTypeRequiredDescription
session_idStringO데이터를 요청하고자 하는 세션의 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>"

2. Response

2.1 200 OK

  • 세션 상세 정보 조회 성공

2.1.1 Body (result field)

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

  • if peculiarities == IN_PROGRESS or NO_REALTIME_POLLING or TOO_SHORT_FOR_ANALYSIS or TOO_MANY_DEFECTS_IN_SLEEP_STAGES: stat object는 null
FieldTypeDescription
timezoneString타임존 (Timezone List)
peculiaritiesList해당 수면 세션의 특이사항이 있을 경우 이를 설명해주는 필드. 해당 필드는 여러 개의 라벨을 포함할 수 있음.

IN_PROGRESS: 세션이 OPEN, CLOSED인 경우
NEVER_SLEPT: 분석 결과 세션 측정시간 동안 전혀 잠을 자지 않았다고 판단 되는 경우
TOO_SHORT_FOR_ANALYSIS: 측정시간이 너무 짧아 유효한 분석을 할 수 없는 경우 (현재 20분 미만)
TOO_LONG_FOR_ANALYSIS: 분석은 정상적으로 되었지만, 세션 측정 시간이 너무 길어 신뢰하기 어려운 경우 (현재 24시간 초과)
TOO_MANY_DEFECTS_IN_SLEEP_STAGES: 오디오 업로드 누락 등의 이유로 오류율이 높아 수면 분석 결과가 충분하지 않은 경우
NO_BREATHING_STABILITY: 고객의 계약 조건상 호흡 안정 분석을 지원하지 않는 경우
NO_REALTIME_POLLING: 고객의 계약 조건상 실시간으로 수면 정보를 확인할 수 없는 경우
missing_data_ratiofloat(0~1 범위 소수점 둘째자리)오디오 업로드 누락 등의 이유로 인한 수면 분석 결과 오류율
sessionSession Object세션 분석 정보
statStat Object?분석 통계 정보

2.1.2 Session Object

  • if state == OPEN: session_end_time은 null
  • if peculiarities == NO_REALTIME_POLLING: sleep_stages는 null
  • if peculiarities == NO_BREATHING_STABILITY: breath_stages는 null
FieldTypeDescription
idStringsession id
stateString (OPEN,CLOSED,COMPLETE)세션의 상태
OPEN: 진행 중인 세션으로, 오디오 업로드가 가능한 상태
CLOSED: 세션 종료 요청이 보내져 종료된 세션. 오디오 파일 업로드 불가능. 업로드된 수면 오디오에 대한 분석이 계속 진행중인 상태
COMPLETE: 세션 종료 후 모든 수면 분석이 완료된 상태
start_timeString (YYYY-MM-DDThh:mm:ss+-hh:mm)세션 시작 시각
예) 2022-08-01T01:31:17+09:00 (요청 타임존이 Asia/Seoul 일 경우)
end_timeString (YYYY-MM-DDThh:mm:ss+-hh:mm)?세션 종료 시각
예) 2022-08-01T01:31:17+09:00 (요청 타임존이 Asia/Seoul 일 경우)
unexpected_end_timeString (YYYY-MM-DDThh:mm:ss+-hh:mm)?비정상 세션 종료 시각. 앱 크래시 등으로 세션이 정상적으로 진행 및 종료되지 못했을 경우, 나중에 클라이언트가 unexpected 파라미터를 1로 하여 세션을 종료시킬 경우 해당 시간이 기록됨. 이 경우 end_time은 마지막까지 업로드된 오디오 파일의 순서 번호를 기준으로 계산됨. 따라서 null이 아닐 경우 비정상 세션.
created_timezoneString세션이 생성된 타임존 (Timezone List)
sleep_stages[Sleep Stages]?수면 단계 리스트
breath_stages[Breath Stages]?호흡 안정도 단계 리스트
snoring_stages[Snoring Stages]?코골이 단계 리스트

2.1.3 Sleep Stages

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

  • 계약 조건이 수면 단계 2레벨인 경우에는 0 (wake), 1 (sleep)
numbersleep stage
-1error (invalid audio, analysis error, etc)
0wake
1light sleep
2deep sleep
3REM sleep

2.1.4 Breath Stages

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

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

2.1.5 Snoring Stages

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

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

2.1.6 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 == NO_BREATHING_STABILITY: 해당 기능이 제공되지 않으므로 time_in_stable_breath, time_in_unstable_breath, stable_breath_ratio, unstable_breath_ratio, breathing_pattern, breathing_index, unstable_breath_count 값은 null
    • if peculiarities == NEVER_SLEPT: 잠을 자지 않은 것이므로 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, breathing_index, light_latency, deep_latency, rem_latency, sleep_cycle, longest_waso, sleep_index 모두 null
  • 새롭게 추가된 메트릭들은 이전 세션들에 대한 데이터를 지원하지 않습니다.
FieldTypeDescriptionExample
sleep_timeString (YYYY-MM-DDThh:mm:ss+-hh:mm)?수면 측정 시작 후 잠들기 까지 걸린 시간2022-08-01T00:30:00+09:00
wake_timeString (YYYY-MM-DDThh:mm:ss+-hh:mm)?잠에서 깨어난 시각2022-08-01T07:30:00+09:00
sleep_indexint(50 <= sleep_index <= 100)?(Beta) 테스트 운영
수면 데이터
87
sleep_latencyInt (seconds)?잠들때까지 걸린 시각1800
wakeup_latencyInt (seconds)?잠에서 깨어난 후 수면 측정을 종료하기까지 걸린 시간1800
light_latencyInt(seconds)?첫 수면 시작으로부터 첫 번째 light가 발생하기까지의 시간300
deep_latencyInt(seconds)?첫 수면 시작으로부터 첫 번째 deep이 발생하기까지의 시600
rem_latencyInt(seconds)?첫 수면 시작으로부터 첫 번째 rem이 발생하기까지의 시간900
time_in_bedInt (seconds)수면 측정 시작 시각부터 수면 측정 종료 시각 까지의 시간28800
time_in_sleep_periodInt (seconds)수면 측정 시간 중 수면 측정 시작으로부터 잠들기 까지 걸린 시간과 잠에서 깨어난 후로부터 수면 측정을 종료하기까지 걸린 시간을 제외한 시간
(time_in_bed - sleep_latency - wakeup_latency)
27000
time_in_sleepInt (seconds)수면 측정 시간 중 실제로 수면 중이었던 시간
이 시간이 deep, light, rem의 3단계로 구분됨
24300
time_in_wakeInt (seconds)수면 도중에 깬 시간2700
time_in_lightInt (seconds)?수면 단계가 light 로 진행된 총 시간5400
time_in_deepInt (seconds)?수면 단계가 deep로 진행된 총 시간5400
time_in_remInt (seconds)?수면 단계가 rem 으로 진행된 총 시간13500
time_in_stable_breathInt (seconds)?호흡 안정 구간이었던 총 시간24300
time_in_unstable_breathInt (seconds)?호흡 불안정 구간이었던 총 시간2700
time_in_snoringInt?코골이가 발생한 총 시간5400
time_in_no_snoringInt?코골이가 발생하지 않은 총 시간23400
sleep_efficiencyfloat (0~1 범위 소수점 둘째자리)수면 측정 시간 중 실제로 잠든 시간의 비율0.84
sleep_ratiofloat (0~1 범위 소수점 둘째자리)?수면 단계 도중 깨지 않고 잔 시간의 비율0.9
wake_ratiofloat (0~1 범위 소수점 둘째자리)?수면 단계 도중 중간에 깬 시간의 비율0.1
light_ratiofloat (0~1 범위 소수점 둘째자리)?수면 단계 도중 light 수면의 비율0.2
deep_ratiofloat (0~1 범위 소수점 둘째자리)?수면 단계 도중 deep 수면의 비율0.2
rem_ratiofloat (0~1 범위 소수점 둘째자리)?rem sleep 비율0.5
stable_breath_ratiofloat (0~1 범위 소수점 둘째자리)?수면 단계 도중 호흡 안정 구간이었던 시간의 비율0.9
unstable_breath_ratiofloat (0~1 범위 소수점 둘째자리)?수면 단계 도중 호흡 불안정 구간이었던 시간의 비율0.1
snoring_ratiofloat (0~1 범위 소수점 둘째자리)?수면 단계 도중 코골이었던 시간의 비율0.3
no_snoring_ratiofloat (0~1 범위 소수점 둘째자리)?수면 단계 도중 코골이가 아니었던 시간의 비율0.7
breathing_indexfloat (0~1 범위 소수점 둘째자리)?호흡 불안정 레벨을 판단하기 위한 값29.7
breathing_patternString (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_countInt?수면 구간 중 wake가 발생한 횟수10
longest_wasoInt(seconds)?수면 구간 중 가장 긴 wake의 시간300
sleep_cycle_countInt?수면 주기의 횟수4
sleep_cycleInt(seconds)?수면 주기 1회당 평균 시간6600
sleep_cycle_timeList 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_countInt?불안정 호흡이 발생한 횟수20
snoring_countInt?코골이 구간이 발생한 횟수11
{
    "detail": "OK",
    "result": {
        "timezone": "UTC",
        "peculiarities": [],
				"missing_data_ratio": 0.02,
        "session": {
            "id": "20230101000000_e5rsv",
            "state": "COMPLETE",
            "start_time": "2023-01-01T00:00:00+00:00",
            "end_time": "2023-01-01T00:20:00+00:00",
            "unexpected_end_time": null,
            "created_timezone": "UTC",
            "sleep_stages": [
                1,
                1,
                0,
                1,
                3,
                1,
                1,
                2,
                2,
                0,
                3,
                1,
                3,
                1,
                3,
                1,
                0,
                0,
                3,
                2,
                0,
                1,
                0,
                0,
                0,
                0,
                2,
                0,
                2,
                2,
                2,
                2,
                1,
                3,
                1,
                1,
                2,
                2,
                3,
                3
            ],
            "breath_stages": [
                1,
                0,
                0,
                1,
                1,
                1,
                0,
                1,
                0,
                1,
                1,
                1,
                1,
                0,
                0,
                1,
                0,
                1,
                1,
                1,
                1,
                1,
                1,
                0,
                0,
                1,
                0,
                1,
                0,
                1,
                1,
                1,
                1,
                1,
                1,
                0,
                0,
                1,
                0,
                1
            ],
            "snoring_stages": [
                1,
                0,
                0,
                1,
                1,
                1,
                0,
                1,
                0,
                1,
                1,
                1,
                1,
                0,
                0,
                1,
                0,
                1,
                1,
                1,
                1,
                1,
                1,
                0,
                0,
                1,
                0,
                1,
                0,
                1,
                1,
                1,
                1,
                1,
                1,
                0,
                0,
                1,
                0,
                1
            ]
        },
        "stat": {
            "sleep_time": "2023-01-01T00:00:00+00:00",
            "wake_time": "2023-01-01T00:20:00+00:00",
            "sleep_index": 85,
            "sleep_latency": 0,
            "wakeup_latency": 0,
            "light_latency": 300,
            "deep_latency": 600,
            "rem_latency": 900,
            "time_in_bed": 1200,
            "time_in_sleep_period": 1200,
            "time_in_sleep": 900,
            "time_in_wake": 300,
            "time_in_light": 360,
            "time_in_deep": 300,
            "time_in_rem": 240,
            "time_in_stable_breath": 420,
            "time_in_unstable_breath": 780,
            "time_in_snoring": 5400,
            "time_in_no_snoring": 23400,
            "sleep_efficiency": 0.75,
            "sleep_ratio": 0.75,
            "wake_ratio": 0.25,
            "light_ratio": 0.3,
            "deep_ratio": 0.25,
            "rem_ratio": 0.2,
            "stable_breath_ratio": 0.35,
            "unstable_breath_ratio": 0.65,
            "snoring_ratio": 0.3,
            "no_snoring_ratio": 0.7,
            "breathing_index": 64.83,
            "breathing_pattern": "SEVERELY_UNSTABLE_BREATH",
            "waso_count": 10,
            "longest_waso": 300,
            "sleep_cycle_count": 4,
            "sleep_cycle": 6600,
            "sleep_cycle_time": [
                "2023-01-01T16:43:03+00:00",
                "2023-01-01T17:47:03+00:00",
                "2023-01-01T19:24:33+00:00",
                "2023-01-01T20:38:33+00:00",
                "2023-01-01T21:55:33+00:00"
            ],
            "unstable_breath_count": 20,
            "snoring_count": 11
        }
    }
}

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

2.3 404 Not Found

  • session_id에 해당되는 세션을 찾지 못한 경우
{
	"detail": "Unable to find the sleep session of id {session_id}"
}