# Health Scores

## Overview

The **Terra Health Scores** product provides four proprietary, science-backed scores designed to give your users a deeper understanding of their health:

* **Immunity Index**
* **Respiratory Health**
* **Sleep Score**
* **Training Stress**
* **Strain Score**

Each score is powered by Terra’s propriety models and interprets complex physiological data into a science-backed health score.

The scores are:

* **Device agnostic:** They work across all supported wearable sources as long as basic metrics such as HRV, sleep, respiratory rate amongst others are collected.
* **Turnkey:** No additional backend setup is needed.
* **Continuously generated:** Once a user is connected, scores appear automatically in the `daily summary` or `sleep` payloads.

***

## How It Works

As soon as your users connect their wearables and data begins syncing, Terra will enrich your payloads with the following scores under the data field `data enrichment` :

<table><thead><tr><th width="190.25">Score Type</th><th width="141.1458740234375">Payload Location</th><th>Frequency</th><th>Source Data Needed</th></tr></thead><tbody><tr><td>🛡️ <strong>Immunity Index</strong></td><td>Daily Summary</td><td>With every new daily payload</td><td>HRV, respiratory rate, body temperature</td></tr><tr><td>🫁 <strong>Respiratory Health</strong></td><td>Daily Summary</td><td>With every new daily payload</td><td>Oxygen saturation, respiratory rate, training</td></tr><tr><td>🏋️‍♀️ <strong>Training Stress</strong></td><td>Daily Summary</td><td>With every new daily payload</td><td>Deep sleep, light sleep, REM, total sleep, body temperature, HRV, RHR, Oxygen Saturation</td></tr><tr><td>💤 <strong>Sleep Score</strong></td><td>Sleep Payload</td><td>With every new sleep payload</td><td>Sleep stages, HR, HRV</td></tr><tr><td>💪🏻 <strong>Strain Score</strong></td><td>Daily Summary</td><td>With every new daily payload</td><td>HRV, RHR</td></tr></tbody></table>

> **Note**: Terra scores appear under the `data_enrichment` field inside the relevant payloads.

RHR, HRV and body temperature metrics are provided by most wearables if worn over night during sleep.

***

## How to Enable Health Scores

Sleep score must be toggled on manually in the dashboard:

1. Log into your Terra Dashboard
2. Go to the **Health Scores** tab
3. Toggle **Health Scores** to “Enabled”
4. Save settings

Sleep scores will now appear in the `sleep` payload for users with eligible data.

***

## How to Receive Health Scores

You do **not** need to implement separate API calls, database logic, or webhook triggers to receive health scores. To receive Terra’s Sleep Score, the following conditions must be met:

1. **Active connection:** Your users have authorized their wearable (via Terra API). See Connect a User for specifics.
2. **Wearables sync necessary metrics:** The necessary metrics (e.g., HRV, respiratory rate, sleep) are available, see **Score Eligibility Criteria.**
3. **The user wears the device (over night):** Metrics like HRV, resting HR, sleep etc. are subject to the user wearing the wearable during sleep.
4. **Baseline values are available:** The user has to wear their device for at least 4 days initially for our propriety score to calibrate and generate a baseline value.
5. **Sufficient data is available:** After the baseline for the user is established, the user has to wear their device at least once in the last 2 weeks.

If users are disconnected, you will not receive new data or scores.

***

## Score Eligibility Criteria

Terra’s health scores are automatically calculated only if sufficient data is available. The following input signals are required to ensure each score is accurate and meaningful.

If any of the **must-have metrics** are missing for a user on a given day, that score will not be generated or may return as `null`.

### Requirements Per Score

#### **💤 Sleep Score**

| Requirement          | Details                                                                 |
| -------------------- | ----------------------------------------------------------------------- |
| **Any sleep metric** | REM, deep sleep, light sleep, total duration                            |
| **Optional**         | HRV, resting heart rate, SpO₂, body temperature enhance score precision |

> At minimum, a valid sleep session with at least one stage or duration is required.

#### **🫁 Respiratory Health**

| Requirement                   | Details                                                                     |
| ----------------------------- | --------------------------------------------------------------------------- |
| **SpO₂ and respiratory rate** | Blood oxygen saturation and respiratory rate measured in breaths per minute |
| **Optional**                  | Training activity to adjust score sensitivity post exercise                 |

> If SpO₂ or respiratory rate are missing, the respiratory health score will be null.

#### **🏋️‍♂️ Training Stress**

| Requirement       | Details                                                                                       |
| ----------------- | --------------------------------------------------------------------------------------------- |
| **HRV and sleep** | Required daily HRV (e.g., RMSSD or SDNN) and sleep metrics                                    |
| Optional          | Steps, HR, training activities help refine intensity detection and training load calibration. |

> If sleep data or HRV is missing, the strain score will be null.

#### **🛡️ Immunity Index**

| Requirement                  | Details                                                        |
| ---------------------------- | -------------------------------------------------------------- |
| **HRV and respiratory rate** | Required daily HRV (e.g., RMSSD or SDNN) and respiratory rate. |
| **Optional**                 | Body temperature enhances score precision                      |

> If HRV or respiratory rate data is missing, the immunity index will be null.

#### 💪🏻 **Strain Score**

| Requirement     | Details                                          |
| --------------- | ------------------------------------------------ |
| **HRV and RHR** | Required daily HRV (e.g., RMSSD or SDNN) and RHR |

> If HRV or RHR data is missing, the strain score will be null.

***

## Understanding Health Score Outputs

Each health score is generated using multiple physiological signals (e.g., HRV, sleep stages, respiration), which are transformed and combined using Terra’s proprietary models.

### 🔢 Score Ranges

| Score              | Range | Interpretation                                              |
| ------------------ | ----- | ----------------------------------------------------------- |
| Sleep Score        | 0–100 | Higher = better sleep quality                               |
| Training Stress    | 0–100 | Higher = higher signs of stress                             |
| Respiratory Health | 0–100 | Higher = better respiratory health                          |
| Immunity Index     | 0–5   | Higher = weakened immunity                                  |
| Strain Score       | -1–1  | Higher = more recovery, lower = higher physiological strain |

### How to Read Contributor Values

Each score has contributors, the underlying physiological metrics that influenced the score. These **do not reflect raw sensor values** (like BPM or °C). Instead, each contributor is:

* Normalized and scaled based on its contribution to the final score
* Weighted according to the model's proprietary algorithm, and adaptive to each individual’s baseline
* Transformed for interpretability and sensitivity

This allows a uniform scoring system across diverse devices and users.

#### Sleep Score Example

```json

"data_enrichment": {
  "sleep_contributors": {
    "rem": 40.34,
    "light": 100,
    "deep": 44.77,
    "total": 96.17,
    "rhr": 100,
    "hrv": 100,
    "temp": 100,
    "oxy": null},
  "sleep_score": 79.13
}
```

**Explanation:**

* `sleep_score`: Final normalized score (0–100)
* `sleep_contributors`: Each value is a transformed signal indicating how much that metric supports healthy sleep. 100 = strong positive influence.

> Note: If a contributor is null, the data was missing or not provided by the device.

#### Immunity Index Example

```json

"data_enrichment": {
  "start_time": "2025-05-20T00:00:00.000000+01:00",
  "immune_contributors": {
    "hrv": 200,
    "respiration": 0,
    "temp": 0
  },
  "immune_index": 0.67
}

```

**Explanation:**

* `immune_index`: Value from **0 to 5**
  * `0` = No sign of immune system weakening
  * `5` = Strong signal of weakened immunity
* Contributor values like `hrv: 200` are **not raw HRV values**, but transformed indicators used by Terra’s model.

> A higher immune index means there are stronger biomarkers of physiological strain that may reflect a stressed or weakened immune system.

#### Strain Score Example

```json
   "data_enrichment": {
      "start_time": "2025-05-20T00:00:00.000000+01:00",
      "strain_contributors": {
        "acute": 0.5,
        "momentum": -0.2,
        "z_slow": 1.3,
        "zcv": -0.8
      },
      "strain_index": 0.35,
      "strain_traffic_light": "GREEN"
    }
```

**Explanation:**

* `strain_index`: Value from -**1 to 1**
  * `+1` = Strong signs of recovery and parasympathetic dominance
  * `0` = Stable, baseline physiological state
  * `-1` = Strong signs of physiological strain and sympathetic activation
* `momentum`**:** 7-day trend of HRV vs HR
* `z_slow`**:** Deviation from 28-day baseline
* `zcv`**:** Stability or instability of HRV variability
* `acute`**:** Short-term (24h) HRV change

> A higher strain\_index indicates recovery and reduced stress load, while a lower (negative) strain\_index indicates accumulating physiological strain.
>
> The strain\_traffic\_light tag (“GREEN”, “AMBER”, “RED”) provides an easy-to-interpret summary based on these values.

***

## Provider vs Terra Scores

Several wearables (e.g., Oura, Fitbit) offer their own native scores. To avoid confusion:

* **Terra Scores** live under `data_enrichment` in the payload.
* **Provider Scores** (like "Stress" or "Sleep" scores) appear under the `scores` section but are **not generated by Terra**.

| Location          | Score Source      |
| ----------------- | ----------------- |
| `data_enrichment` | Terra             |
| `scores`          | Native device/app |

***

## Adjusting the Model

Each health score is powered by a proprietary Terra model. However, if you’d like to customize the weight or logic behind specific score components:

* Visit the **Terra Dashboard**
* Navigate to the **Health Scores section**
* Modify parameters such as HRV sensitivity, activity thresholds, or sleep weightings

These changes apply **in real time** and update future score outputs.

***

## Questions?

If you’re unsure whether your data includes scores or if you’re not seeing expected results, check:

* The `data_enrichment` object in your latest payload - daily or sleep payload
* That the user’s wearable is actively syncing data
* That the user has at least 4 days of relevant baseline data
* That the user has worn the wearable to sleep
* Your user has had generated the necessary underlying metrics in the past 2 weeks


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tryterra.co/user-engagement/health-scores.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.