Sleep Tools
Four tools for accessing your sleep sessions, stages, and quality metrics.
get-sleep-collection
Retrieve a paginated list of sleep activities with optional date filtering.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
start_date | string | No | - | Start date in ISO 8601 format |
end_date | string | No | - | End date in ISO 8601 format |
limit | number | No | 25 | Maximum records to return |
Example Questions
- "Show me my sleep data from last week"
- "Get all sleep records from December"
- "Fetch my most recent sleep sessions"
Response Fields
| Field | Description |
|---|---|
id | Unique sleep session ID |
start / end | Sleep session timestamps |
nap | Boolean - true if this was a nap |
score.sleep_performance_percentage | How well you met your sleep need |
score.sleep_efficiency_percentage | Time asleep vs time in bed |
score.respiratory_rate | Breaths per minute |
score.stage_summary.* | Time in each sleep stage (ms) |
get-sleep-by-id
Get detailed information about a specific sleep activity.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
sleep_id | string | Yes | UUID of the sleep activity |
Example Questions
- "Get details for this specific sleep session"
- "Show me the breakdown of that night's sleep"
get-recent-sleep
Convenience tool to get sleep activities from the last N days.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
days | number | No | 7 | Number of days to look back |
Example Questions
- "How have I been sleeping this week?"
- "Show my sleep for the past 2 weeks"
- "Get my recent sleep data"
get-sleep-summary
Get aggregated sleep metrics and averages for a date range. Automatically handles pagination to include all data.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Start date in ISO 8601 format |
end_date | string | Yes | End date in ISO 8601 format |
Example Questions
- "What's my average sleep performance this month?"
- "How much deep sleep am I getting on average?"
- "Summarize my sleep patterns for December"
- "Compare my sleep efficiency over the past two weeks"
Response Fields
| Field | Description |
|---|---|
period | Date range and number of days |
totals.sleep_sessions | Number of sleep sessions |
totals.naps | Number of naps |
averages.sleep_duration_hours | Average sleep time |
averages.sleep_performance_percentage | Average performance score |
stage_averages.* | Average time in each stage |
Understanding Sleep Metrics
Sleep Stages
| Stage | Description |
|---|---|
| Light Sleep | N1 and N2 sleep stages - transition sleep |
| Deep Sleep | N3 slow-wave sleep - most physically restorative |
| REM Sleep | Rapid eye movement - dreams, memory consolidation |
| Awake | Time spent awake during sleep period |
Key Metrics
| Metric | Range | What It Means |
|---|---|---|
| Sleep Performance | 0-100% | How well you met your sleep need |
| Sleep Efficiency | 0-100% | Percentage of time in bed actually sleeping |
| Sleep Consistency | 0-100% | How regular your sleep schedule is |
| Respiratory Rate | ~12-20 | Breaths per minute during sleep |
Score States
| State | Description |
|---|---|
SCORED | Complete analysis with all metrics |
PENDING_SCORE | Still being processed by WHOOP |
UNSCORABLE | Insufficient data (e.g., session too short) |
Time Values
All durations from WHOOP are in milliseconds. Summary tools convert to hours.
hours = milliseconds / 3,600,000