---
title: "Get sleep chart data with heart rate overlay"
method: GET
path: "/api/health/sleep-chart"
tags: ["Health"]
---

# Get sleep chart data with heart rate overlay

`GET /api/health/sleep-chart`

## Request

- Base URL: `https://api.hiyd.ai`
- URL: `https://api.hiyd.ai/api/health/sleep-chart`
- Auth: HTTP bearer

Returns sleep session data with sleep stages timeline and heart rate data for visualization

## Query parameters

- `date` string, date
- `granularity` 'day' | 'week' | 'month'
- `start` string, date
- `time_zone` string

## Response `200`

Sleep chart data retrieved successfully

- object
  - `date` string, date
  - `sleep_session` object
    - `bedtime` string, date-time
    - `wakeup_time` string, date-time
    - `total_duration` string
    - `total_duration_minutes` number
    - `sleep_score` number
  - `sleep_stages` object[]
    - `stage` string
    - `start_time` string
    - `end_time` string
    - `duration_minutes` number
  - `heart_rate_data` object[]
    - `timestamp` string
    - `heart_rate` number
  - `summary` object
    - `time_in_bed` string
    - `time_asleep` string
    - `deep_sleep` string
    - `light_sleep` string
    - `rem_sleep` string
    - `awake` string
    - `avg_heart_rate` number
    - `lowest_heart_rate` number
  - `source` 'band' | 'demo'
  - `stages_source` 'band' | 'demo' | 'none': none = a band night with no stored stage timeline
  - `stage_timeline` object[]: Stage segments sorted by start_time, lowercase stage names (awake, light, deep, rem), UTC instants ending in Z. For a band night the legacy sleep_stages field is [] and this one carries the timeline.
    - `stage` string
    - `start_time` string, date-time
    - `end_time` string, date-time
    - `duration_minutes` number
  - `bedtime` string, date-time, nullable
  - `wakeup_time` string, date-time, nullable
  - `time_zone` string, nullable: The zone the band night was staged in (null for demo rows)

## Other responses

- `400`: Malformed date
- `404`: No sleep data found for the specified date

---

[API](https://skmtc.dev/hiyd/apis/hiyd-backend-api.md) - [All operations](https://skmtc.dev/hiyd/apis/hiyd-backend-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hiyd/apis/hiyd-backend-api/revisions/23598d347e1b?raw)