---
title: "List Health Scores"
method: GET
path: "/api/v1/users/{user_id}/health-scores"
tags: ["External: Health Scores"]
---

# List Health Scores

`GET /api/v1/users/{user_id}/health-scores`

Returns health scores (sleep, recovery, readiness, etc.) for a user.

## Path parameters

- `user_id` string, uuid, required

## Query parameters

- `start_date` string, date-time, nullable — ISO 8601 datetime (e.g. `2023-11-07T05:31:56Z`) or Unix timestamp in seconds. Date-only strings (e.g. `2023-11-07`) are also accepted and normalized to midnight UTC.
- `end_date` string, date-time, nullable — ISO 8601 datetime (e.g. `2023-11-07T05:31:56Z`) or Unix timestamp in seconds. Date-only strings (e.g. `2023-11-07`) are also accepted and normalized to midnight UTC.
- `category` 'sleep' | 'recovery' | 'readiness' | 'activity' | 'stress' | 'resilience' | 'body_battery' | 'strain'
- `provider` 'apple' | 'samsung' | 'garmin' | 'google' | 'polar' | 'suunto' | 'whoop' | 'strava' | 'oura' | 'fitbit' | 'ultrahuman' | 'sensorbio' | 'unknown' | 'internal' — Supported data providers.
- `limit` integer
- `offset` integer

## Headers

- `X-Open-Wearables-API-Key` string, nullable

## Response `200`

Successful Response

- PaginatedResponseHealthScoreResponse
  - `data` HealthScoreResponse[], required
    - `category` 'sleep' | 'recovery' | 'readiness' | 'activity' | 'stress' | 'resilience' | 'body_battery' | 'strain', required
    - `value` union — Overall numeric score. Range varies by provider and category — see HEALTH_SCORE_RANGES for scale.
      - number
      - integer
    - `qualifier` string, nullable — Textual rating from the provider, e.g. GOOD or EXCELLENT
    - `recorded_at` string, date-time, required
    - `zone_offset` string, nullable — Timezone offset in the format '+01:00' or '-05:30'
    - `components` object, nullable
    - `id` string, uuid, required
    - `data_source_id` string, uuid, nullable, required
    - `provider` 'apple' | 'samsung' | 'garmin' | 'google' | 'polar' | 'suunto' | 'whoop' | 'strava' | 'oura' | 'fitbit' | 'ultrahuman' | 'sensorbio' | 'unknown' | 'internal', required — Supported data providers.
  - `pagination` Pagination, required
    - `next_cursor` string, nullable — Cursor to fetch next page, null if no more data
    - `previous_cursor` string, nullable — Cursor to fetch previous page
    - `has_more` boolean, required — Whether more data is available
    - `total_count` integer, nullable — Total number of records matching the query
  - `metadata` TimeseriesMetadata, required
    - `resolution` 'raw' | '1min' | '5min' | '15min' | '1hour', nullable
    - `sample_count` integer, nullable
    - `start_time` string, date-time, nullable
    - `end_time` string, date-time, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/openwearables/apis/open-wearables-api.md) · [All operations](https://skmtc.net/openwearables/apis/open-wearables-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openwearables/open-wearables-api/revisions/8c15cc93d210/schema)