---
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`

## Request

- Base URL: `https://api.openwearables.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.openwearables.io/api/v1/users/{user_id}/health-scores`
- Auth: OAuth 2 (password, token URL `/api/v1/auth/login`)

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 cover the whole day, so a date-only range includes both boundary days.
- `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 cover the whole day, so a date-only range includes both boundary days.
- `category` 'sleep' | 'recovery' | 'readiness' | 'activity' | 'stress' | 'resilience' | 'body_battery' | 'strain'
- `provider` 'apple' | 'samsung' | 'garmin' | 'health_connect' | 'google_health' | 'polar' | 'suunto' | 'whoop' | 'strava' | 'oura' | 'fitbit' | 'ultrahuman' | 'sensorbio' | 'withings' | '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' | 'health_connect' | 'google_health' | 'polar' | 'suunto' | 'whoop' | 'strava' | 'oura' | 'fitbit' | 'ultrahuman' | 'sensorbio' | 'withings' | 'unknown' | 'internal', required: Supported data providers.
    - `event_record_id` string, uuid, nullable: The sleep session or workout this score describes. Null for whole-day scores.
  - `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': Bucket width requested when reading time series. RAW returns stored samples untouched.
    - `sample_count` integer, nullable
    - `start_time` string, date-time, nullable
    - `end_time` string, date-time, nullable

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-16** `b628830d5f47`: 1 breaking, 2 warning, 3 info
  - removed the enum value `google` from the property `anyOf[subschema #1: ProviderName]/` of the `query` request parameter `provider`
  - added the new `google_health` enum value to the `data/items/provider/anyOf[subschema #1: ProviderName]/` response property for the response status `200`
  - added the new `health_connect` enum value to the `data/items/provider/anyOf[subschema #1: ProviderName]/` response property for the response status `200`
  - added the enum value `google_health` to the property `anyOf[subschema #1: ProviderName]/` of the `query` request parameter `provider`
  - …2 more
- **2026-09-09** `7c7514614b91`: 1 warning, 1 info
  - added the new `withings` enum value to the `data/items/provider/anyOf[subschema #1: ProviderName]/` response property for the response status `200`
  - added the enum value `withings` to the property `anyOf[subschema #1: ProviderName]/` of the `query` request parameter `provider`
- **2026-08-25** `427d02add648`: 1 info
  - added the optional property `data/items/event_record_id` to the response with the `200` status
- **2026-07-26** `e8a9270a1ee1`: 1 warning, 1 info
  - added the new `sensorbio` enum value to the `data/items/provider/anyOf[subschema #1: ProviderName]/` response property for the response status `200`
  - added the enum value `sensorbio` to the property `anyOf[subschema #1: ProviderName]/` of the `query` request parameter `provider`

[Operation history](https://skmtc.dev/openwearables/apis/open-wearables-api/changes/api/v1/users/:user_id/health-scores/get.md)

---

[API](https://skmtc.dev/openwearables/apis/open-wearables-api.md) · [All operations](https://skmtc.dev/openwearables/apis/open-wearables-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openwearables/apis/open-wearables-api/revisions/c9016a165d04?raw)