For AI agents: visit https://docs.asleep.ai/llms.txt for an index of all pages formatted in Markdown and endpoints in OpenAPI. Append .md to any documentation page URL to get its markdown version.
분석 구간은 요청할 때마다 새로 정해집니다. 구간 없이 reanalyze(sessionId:)를 호출하면 이전에 지정한 구간이 유지되지 않고 측정 전체로 다시 분석됩니다. 구간을 유지하려면 같은 구간을 다시 넘기세요.
Reports를 만든 config에 userId가 있어야 합니다. 없으면 요청을 보내지 않고 reanalyzeFailed로 실패합니다
completionBlock은 메인 스레드에서 호출된다는 보장이 없습니다. UI를 갱신할 때는 메인 스레드로 전환하세요.
🚧
재분석으로 구간을 바꿔도 녹음 파일은 따라오지 않습니다.
녹음 파일은 첫 분석이 끝나는 시점에 그때의 분석 구간을 기준으로 정리되며, 구간 밖의 파일은 그때 삭제됩니다. 재분석은 서버에만 요청을 보내고 기기에 저장된 파일은 건드리지 않으므로, 이미 삭제된 구간의 녹음은 다시 생기지 않습니다.
구간을 넓히면 넓어진 부분의 녹음은 없습니다
첫 구간과 겹치지 않는 구간으로 바꾸면 녹음이 하나도 없습니다
첫 구간의 일부로 좁히면, 그 안에서 원래 남아 있던 파일만 조회됩니다
audio_segments.json 에는 측정 전체 구간의 행이 그대로 남고 파일이 없는 구간만 경로가 비어 있습니다. 앱에서는 "녹음이 원래 없던 구간"과 "정리되어 삭제된 구간"을 구분할 수 없습니다.
넓은 구간의 녹음이 필요하다면 측정을 종료할 때 그 구간으로 분석을 요청하세요.
에러 코드
AsleepError
HTTP
SDK 에러 코드 (베타)
상황
invalidParameter
-
-
시작 시각이 종료 시각보다 늦거나 같음 (요청 전 확인)
reanalyzeFailed
-
-
Reports를 만든 config에 userId 없음
unknown
-
-
네트워크 오류 (async에서는 시스템 에러가 그대로 throw됩니다)
httpStatus
400
30400
잘못된 시작 · 종료 시각
httpStatus
401
30401
인증 실패
httpStatus
403
30403
재분석 권한 없음
httpStatus
404
30404
세션을 찾을 수 없음
httpStatus
409
30409
지금은 재분석할 수 없음 (이미 재분석 중 등)
httpStatus
410
30410
데이터 보관 기간 만료
httpStatus
422
30422
아직 측정 중인 세션
httpStatus
5xx
30500
서버 오류
SDK 에러 코드는 httpStatus 의 errorCode 로 전달되는 5자리 코드입니다(베타). 현재는 HTTP 상태 코드 기준 분기를 권장합니다.
🚧
httpStatus(code: 409)를 받았을 때 무한 재시도는 피하세요. 재분석이 진행 중일 때뿐 아니라 재분석할 수 없는 세션에서도 계속 반환될 수 있습니다. 재시도한다면 횟수와 간격을 정해두세요.
Data Types
Asleep.Model.Report
struct Report {
let timezone: String
let peculiarities: [Peculiarity]
let missingDataRatio: Float
let session: Session
let stat: Stat?
let analysis: Analysis?
}
enum Peculiarity {
case inProgress
case neverSlept
case tooShortForAnalysis
case tooLongForAnalysis
case tooManyDefectsInSleepStages
case noBreathingStability
case noRealtimePolling
}
Property Name
Type
Description
timezone
String
분석 결과의 시간대를 해당 timezone으로 변경해서 반환 (예: UTC, Asia/Seoul)
peculiarities
[Asleep.Model.Peculiarity]
해당 수면 세션의 특이사항을 설명하는 필드. 여러 개의 라벨 포함 가능.
missingDataRatio
Float
오디오 업로드 누락 등의 이유로 인한 수면 분석 결과 오류율 (0~1.0)
session
Asleep.Model.Session
세션 분석 정보
stat
Asleep.Model.Stat
분석 통계 정보
analysis
Asleep.Model.Analysis?
서버가 분석한 구간 정보. 세션이 아직 측정 중이면 구간이 정해지지 않아 nil
Asleep.Model.Session
struct Session {
let id: String
let state: State
let startTime: Date
let endTime: Date?
let unexpectedEndTime: Date?
let createdTimezone: String
let sleepStages: [Int]?
let breathStages: [Int]?
let snoringStages: [Int]?
let sleepStageProbs: [[Float]]?
let breathStageProbs: [[Float]]?
let snoringStageProbs: [[Float]]?
let measurementStartTime: Date?
let measurementEndTime: Date?
}
enum State {
case open
case closed
case complete
}
struct Stat {
let sleepEfficiency: Float?
let sleepLatency: Int?
let sleepTime: Date?
let wakeupLatency: Int?
let wakeTime: Date?
let lightLatency: Int?
let deepLatency: Int?
let remLatency: Int?
let timeInWake: Int?
let timeInSleepPeriod: Int?
let timeInSleep: Int?
let timeInBed: Int?
let timeInRem: Int?
let timeInLight: Int?
let timeInDeep: Int?
let timeInStableBreath: Int?
let timeInUnstableBreath: Int?
let timeInSnoring: Int?
let timeInNoSnoring: Int?
let wakeRatio: Float?
let sleepRatio: Float?
let remRatio: Float?
let lightRatio: Float?
let deepRatio: Float?
let stableBreathRatio: Float?
let unstableBreathRatio: Float?
let snoringRatio: Float?
let noSnoringRatio: Float?
let unstableBreathCount: Int?
let breathingPattern: BreathingPattern?
let breathingIndex: Float?
let sleepCycle: Int?
let sleepCycleCount: Int?
let sleepCycleTime: [Date]?
let wasoCount: Int?
let longestWaso: Int?
let sleepIndex: Int?
let snoringCount: Int?
}
Property Name
Type
Description
sleepEfficiency
Float?
수면 측정 시간 중 실제로 잠든 시간의 비율
sleepLatency
Int?
잠들때까지 걸린 시간
sleepTime
Date?
수면 측정 시작 후 잠들기까지 걸린 시간
wakeupLatency
Int?
잠에서 깨어난 후 수면 측정을 종료하기까지 걸린 시간
wakeTime
Date?
잠에서 깨어난 시각
lightLatency
Int?
첫 수면 시작으로부터 첫 번째 light가 발생하기까지의 시간
deepLatency
Int?
첫 수면 시작으로부터 첫 번째 deep이 발생하기까지의 시간
remLatency
Int?
첫 수면 시작으로부터 첫 번째 rem이 발생하기까지의 시간
timeInWake
Int?
수면 도중에 깬 시간
timeInSleepPeriod
Int?
수면 측정 시간 중 수면 측정 시작으로부터 잠들기 까지 걸린 시간과 잠에서 깨어난 후로부터 수면 측정을 종료하기까지 걸린 시간을 제외한 시간
timeInSleep
Int?
수면 측정 시간 중 실제로 수면 중이었던 시간 (이 시간이 deep, light, rem의 3단계로 구분됨)
수면 주기 전환 기준 시각 (예: [첫번째 수면 주기 시작 시각, 첫번째 수면 주기 종료 시각, 두번째 수면 주기 종료 시각, ..., 마지막 수면 주기 종료 시각])
wasoCount
Int?
수면 구간 중 wake가 발생한 횟수
longestWaso
Int?
수면 구간 중 가장 긴 wake의 시간
sleepIndex
Int?
수면 데이터 분포를 학습하여 정의된 수면의 질을 종합적으로 대표하는 지표 (수면 점수)
snoringCount
Int?
코골이 구간의 발생한 횟수
Asleep.Model.Analysis
struct Analysis {
let startEpochIndex: Int
let endEpochIndex: Int
let epochDurations: [Int]
let totalEpochCount: Int
var epochCount: Int { get }
func contains(seq: Int) -> Bool
}
Property Name
Type
Description
startEpochIndex
Int
분석 구간의 첫 epoch 번호 (측정 전체 기준, 포함)
endEpochIndex
Int
분석 구간의 마지막 epoch 다음 번호 (미포함)
epochDurations
[Int]
구간 안 각 epoch의 길이(초). 구간 경계가 epoch 경계와 맞지 않으면 첫 · 마지막 값이 30보다 작을 수 있습니다
totalEpochCount
Int
측정 전체의 epoch 수
epochCount
Int
구간에 포함된 epoch 수
contains(seq:)
Bool
측정 전체 기준 epoch 번호 seq가 분석 구간에 포함되는지 여부
🚧
구간을 지정하면 stage 배열의 인덱스는 측정 시작 기준이 아닙니다.sleepStages[i]는 측정 전체에서 startEpochIndex + i번째 epoch(30초)입니다. 배열 인덱스로 시각을 계산하거나 녹음 파일과 매칭할 때는 startEpochIndex를 더해주세요.
Asleep.Model.SleepSession
struct SleepSession {
let sessionId: String
let state: State
let sessionStartTime: Date
let sessionEndTime: Date?
let createdTimezone: String
let unexpectedEndTime: Date?
let lastReceivedSeqNum: Int?
let timeInBed: Int?
}
enum State {
case open
case closed
case complete
}
struct AverageReport {
let period: Period
let peculiarities: [Peculiarity]
let averageStats: AverageStats?
let neverSleptSessions: [NeverSleptSession]
let sleptSessions: [SleptSession]
}
수면 세션들의 평균을 구할 때 특이사항. (NO_BREATHING_STABILITY: 호흡 안정 분석 미지원)
averageStats
Asleep.Model.AverageStats?
slept_sessions의 수면 메트릭들의 평균들을 가지는 객체
neverSleptSessions
Array<Asleep.Model.NeverSleptSession>
세션 측정시간 동안 전혀 잠을 자지 않았다고 판단 되는 세션들의 목록
sleptSessions
Array<Asleep.Model.SleptSession>
세션 측정시간 동안 잠을 잤다고 판단 되는 세션들의 목록
Asleep.Model.Period
struct Period {
let timezone: String
let startDate: Date
let endDate: Date
}
Property Name
Type
Description
timezone
String
요청한 타임존 (예: UTC, Asia/Seoul)
startDate
Date
요청한 시작 시간
endDate
Date
요청한 종료 시간
Asleep.Model.AverageStats
struct AverageStats {
let startTime: String
let endTime: String
let sleepTime: String
let wakeTime: String
let sleepLatency: Int
let wakeupLatency: Int
let timeInBed: Int
let timeInSleepPeriod: Int
let timeInSleep: Int
let timeInWake: Int
let timeInLight: Int?
let timeInDeep: Int?
let timeInRem: Int?
let timeInSnoring: Int?
let timeInNoSnoring: Int?
let sleepEfficiency: Double
let wakeRatio: Double
let sleepRatio: Double
let lightRatio: Double?
let deepRatio: Double?
let remRatio: Double?
let snoringRatio: Double?
let noSnoringRatio: Double?
let wasoCount: Int
let longestWaso: Int
let sleepCycleCount: Int?
let snoringCount: Int?
}
Property Name
Type
Description
startTime
String (hh:mm:ss)
세션 시작 시각
endTime
String (hh:mm:ss)
세션 종료 시각
sleepTime
String (hh:mm:ss)
잠들때까지 걸린 시각
wakeTime
String (hh:mm:ss)
잠에서 깨어난 시각
sleepLatency
Int
잠들때까지 걸린 시각
wakeupLatency
Int
잠에서 깨어난 후 수면 측정을 종료하기까지 걸린 시간
timeInBed
Int
수면 측정 시작 시각부터 수면 측정 종료 시각 까지의 시간
timeInSleepPeriod
Int
수면 측정 시간 중 수면 측정 시작으로부터 잠들기 까지 걸린 시간과 잠에서 깨어난 후로부터 수면 측정을 종료하기까지 걸린 시간을 제외한 시간
timeInSleep
Int
수면 측정 시간 중 실제로 수면 중이었던 시간 (이 시간이 deep, light, rem의 3단계로 구분됨)
timeInWake
Int
수면 도중에 깬 시간
timeInLight
Int?
수면 단계가 light 로 진행된 총 시간
timeInDeep
Int?
수면 단계가 deep로 진행된 총 시간
timeInRem
Int?
수면 단계가 rem 으로 진행된 총 시간
timeInSnoring
Int?
코골이가 발생한 총 시간
timeInNoSnoring
Int?
코골이가 발생하지 않은 총 시간
sleepEfficiency
Double
수면 측정 시간 중 실제로 잠든 시간의 비율
wakeRatio
Double
수면 단계 도중 중간에 깬 시간의 비율
sleepRatio
Double
수면 단계 도중 깨지 않고 잔 시간의 비율
lightRatio
Double?
수면 단계 도중 light 수면의 비율
deepRatio
Double?
수면 단계 도중 deep 수면의 비율
remRatio
Double?
rem sleep 비율
snoringRatio
Double?
수면 단계 도중 코골이었던 시간의 비율
noSnoringRatio
Double?
수면 단계 도중 코골이가 아니었던 시간의 비율
wasoCount
Int
수면 구간 중 wake가 발생한 횟수
longestWaso
Int
수면 구간 중 가장 긴 wake의 시간
sleepCycleCount
Int?
수면 주기의 횟수
snoringCount
Int?
코골이 구간의 발생한 횟수
Asleep.Model.NeverSleptSession
struct NeverSleptSession {
let id: String
let startTime: Date
let endTime: Date
let completedTime: Date
}
Property Name
Type
Description
id
String
session id
startTime
Date
세션 시작 시각
endTime
Date
세션 종료 시각
completedTime
Date
세션 분석 완료 시각
Asleep.Model.SleptSession
struct SleptSession {
let id: String
let createdTimezone: String
let startTime: Date
let endTime: Date
let completedTime: Date
let sleepEfficiency: Double
let sleepLatency: Int?
let wakeupLatency: Int?
let lightLatency: Int?
let deepLatency: Int?
let remLatency: Int?
let sleepTime: Date?
let wakeTime: Date?
let timeInWake: Int
let timeInSleepPeriod: Int
let timeInSleep: Int
let timeInBed: Int
let timeInRem: Int?
let timeInLight: Int?
let timeInDeep: Int?
let timeInSnoring: Int?
let timeInNoSnoring: Int?
let wakeRatio: Double
let sleepRatio: Double
let remRatio: Double?
let lightRatio: Double?
let deepRatio: Double?
let snoringRatio: Double?
let noSnoringRatio: Double?
let sleepCycle: Int?
let sleepCycleCount: Int?
let wasoCount: Int?
let longestWaso: Int?
let snoringCount: Int?
}