# Health Scores

## Overview

The **Terra Health Scores** product provides **14 proprietary, science-backed scores** designed to give your users a deeper understanding of their health, recovery, and training load. Scores are organized by which payload they enrich:

* **Daily summary** scores: Immunity Index, Strain Index, Resilience, Respiratory Health, Training Stress (V1 & V2)
* **Sleep** scores: Sleep Score (V1 & V2), Readiness, Respiratory Health V2
* **Activity** scores: Activity Strain, Activity Efficiency, Activity RCRS, Activity TRIMP

Each score is powered by Terra’s proprietary models and translates complex physiological data into a single, interpretable health signal.

The scores are:

* **Device agnostic:** They work across all supported wearable sources as long as the underlying metrics (HRV, sleep stages, respiratory rate, heart rate, etc.) are collected.
* **Turnkey:** No additional backend setup is needed.
* **Continuously generated:** Once a user is connected, scores appear automatically in the `daily`, `sleep`, or `activity` 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_enrichment` field.

### Daily payload

<table><thead><tr><th width="220">Score</th><th width="180">JSON field</th><th>Frequency</th><th>Source Data Needed</th></tr></thead><tbody><tr><td>🛡️ <strong>Immunity Index</strong></td><td><code>immune_index</code></td><td>With every new daily payload</td><td>HRV, respiratory rate, body temperature</td></tr><tr><td>💪🏻 <strong>Strain Index</strong></td><td><code>strain_index</code></td><td>With every new daily payload</td><td>HRV (7-day and 28-day baselines), average heart rate</td></tr><tr><td>🌱 <strong>Resilience</strong></td><td><code>resilience_score</code></td><td>With every new daily payload</td><td>Body temperature, respiratory rate, RHR, HRV, oxygen saturation (with 30-day baselines)</td></tr><tr><td>🫁 <strong>Respiratory Health</strong></td><td><code>respiratory_score</code></td><td>With every new daily payload</td><td>Oxygen saturation, respiratory rate (30-day baseline)</td></tr><tr><td>🏋️‍♀️ <strong>Training Stress</strong></td><td><code>total_stress_score</code></td><td>With every new daily payload</td><td>Sleep score, step count (7-day), activity duration in light / moderate / vigorous intensity zones</td></tr><tr><td>🏋️‍♂️ <strong>Training Stress V2</strong></td><td><code>total_stress_score_v2</code></td><td>With every new daily payload</td><td>Sleep score V2, step count (7-day), heart rate zones (7-day)</td></tr></tbody></table>

### Sleep payload

<table><thead><tr><th width="220">Score</th><th width="180">JSON field</th><th>Frequency</th><th>Source Data Needed</th></tr></thead><tbody><tr><td>💤 <strong>Sleep Score</strong></td><td><code>sleep_score</code></td><td>With every new sleep payload</td><td>Sleep stages (REM, deep, light, total), RHR, HRV, body temperature, SpO₂</td></tr><tr><td>💤 <strong>Sleep Score V2</strong></td><td><code>sleep_score_v2</code></td><td>With every new sleep payload</td><td>Sleep stages, average HR, body temperature, HRV (14-day baseline)</td></tr><tr><td>🌅 <strong>Readiness</strong></td><td><code>readiness_score</code></td><td>With every new sleep payload</td><td>Sleep stages, RHR (30-day), HRV (30-day), body temperature, respiratory rate, SpO₂</td></tr><tr><td>🫁 <strong>Respiratory Health V2</strong></td><td><code>respiratory_score_v2</code></td><td>With every new sleep payload</td><td>SpO₂, respiratory rate (14-day baseline)</td></tr></tbody></table>

### Activity payload

<table><thead><tr><th width="220">Score</th><th width="180">JSON field</th><th>Frequency</th><th>Source Data Needed</th></tr></thead><tbody><tr><td>🔥 <strong>Activity Strain</strong></td><td><code>strain_score</code></td><td>With every new activity payload</td><td>Average heart rate, activity duration, 14-day max HR</td></tr><tr><td>⚡ <strong>Activity Efficiency</strong></td><td><code>efficiency_score</code></td><td>With every new activity payload</td><td>Average speed, average heart rate, 14-day max HR</td></tr><tr><td>❤️ <strong>Activity RCRS</strong></td><td><code>rcrs_score</code></td><td>With every new activity payload</td><td>Average heart rate, activity duration, 30-day max HR</td></tr><tr><td>📈 <strong>Activity TRIMP</strong></td><td><code>trimp_score</code></td><td>With every new activity payload</td><td>Average heart rate, activity duration, 30-day max HR</td></tr></tbody></table>

> **Note**: Terra scores appear under the `data_enrichment` field inside each relevant payload (daily, sleep, or activity).

RHR, HRV, body temperature, and respiratory rate metrics are provided by most wearables if worn overnight during sleep.

***

## How to Enable Health Scores

Some scores must be toggled on manually in the dashboard:

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

Enabled scores will then appear in the relevant payloads 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 scores, 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 required metrics (e.g., HRV, respiratory rate, sleep stages) are available — see **Score Eligibility Criteria** below.
3. **The user wears the device (overnight):** Metrics like HRV, resting HR, and sleep stages depend on 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 proprietary models to calibrate and generate baseline values. Some scores use longer baselines (14-day or 30-day) — those will continue to refine over time.
5. **Sufficient data is available:** After a user's baseline 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** / **💤 Sleep Score V2**

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

#### **🌅 Readiness**

| Requirement              | Details                                                                                 |
| ------------------------ | --------------------------------------------------------------------------------------- |
| **Sleep stages and HRV** | Required REM, deep and total sleep, plus daily HRV (RMSSD or SDNN) with 30-day baseline |
| **Optional**             | RHR, body temperature, SpO₂, respiratory rate refine the score                          |

> Readiness requires at least \~3 hours of recorded sleep; sessions shorter than that produce a 0 sleep contributor.

#### **🫁 Respiratory Health** / **🫁 Respiratory Health V2**

| 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 is missing, the respiratory health score will be null. V2 is computed on the sleep payload; the legacy version still appears on the daily payload.

#### **🏋️ Training Stress** / **🏋️ Training Stress V2**

| Requirement       | Details                                                                                                                                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **HRV and sleep** | Required daily HRV (e.g., RMSSD or SDNN) and a valid sleep score                                                                                                                                              |
| Optional          | Steps (7-day history) refine training calibration. Activity duration in light, moderate, and vigorous intensity zones (when provided by the wearable in the daily payload) sharpens the training-load signal. |

> If sleep data or HRV is missing, the training stress score will be null. If intensity-zone duration is not provided by the wearable, the training contributor falls back to zero rather than estimating from heart-rate samples.

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

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

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

#### **💪🏻 Strain Index**

| Requirement    | Details                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------ |
| **HRV and HR** | Required daily HRV (e.g., RMSSD or SDNN) and average heart rate, with 7-day and 28-day baselines |

> If HRV or HR data is missing, the strain index will be null.

#### **🌱 Resilience**

| Requirement                | Details                                                                             |
| -------------------------- | ----------------------------------------------------------------------------------- |
| **HRV, RHR and resp rate** | Required daily HRV, resting heart rate, and respiratory rate, with 30-day baselines |
| **Optional**               | Body temperature and SpO₂ refine the score                                          |

> Resilience is generated once enough history exists to compute 30-day baselines for the must-have metrics.

#### **🔥 Activity Strain / ⚡ Activity Efficiency**

| Requirement            | Details                                                                                      |
| ---------------------- | -------------------------------------------------------------------------------------------- |
| **HR during activity** | Activity must include average heart rate; HR range (max − min) must exceed 30 bpm            |
| **For Efficiency**     | Activity must additionally include average speed                                             |
| **Baseline**           | A 14-day rolling window of max HR is used; new users will see scores stabilize after 2 weeks |

> Activities without valid heart-rate data (e.g., flat-line HR or HR range below 30 bpm) will not produce a score.

#### **❤️ Activity RCRS / 📈 Activity TRIMP**

| Requirement            | Details                                                                                        |
| ---------------------- | ---------------------------------------------------------------------------------------------- |
| **HR during activity** | Average heart rate and activity duration are required; HR range (max − min) must exceed 30 bpm |
| **Baseline**           | A 30-day rolling window of max HR is used                                                      |

> RCRS and TRIMP are physiological load metrics — they are not normalized to a 0–100 range, so values scale with workout intensity and duration.

***

## 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                                       |
| Sleep Score V2        | 0–100          | Higher = better sleep quality (revised algorithm)                   |
| Readiness             | 0–100          | Higher = better readiness for the day                               |
| Respiratory Health    | 0–100          | Higher = better respiratory health                                  |
| Respiratory Health V2 | 0–100          | Higher = better respiratory health (revised algorithm)              |
| Training Stress       | 0–100          | Higher = higher signs of stress                                     |
| Training Stress V2    | 0–100          | Higher = higher signs of stress (revised algorithm)                 |
| Immunity Index        | 0–5            | Higher = weakened immunity                                          |
| Strain Index          | −50 to 50      | Positive = recovery, negative = strain (see traffic light)          |
| Resilience            | 0–100          | Higher = greater resilience and recovery capacity                   |
| Activity Strain       | 0–100          | Higher = more strain during the workout                             |
| Activity Efficiency   | 0–100          | Higher = better cardiovascular efficiency for the workout           |
| Activity RCRS         | 0+ (unbounded) | Relative cardiovascular response — scales with intensity × duration |
| Activity TRIMP        | 0+ (unbounded) | Training impulse — scales with intensity × duration                 |

### 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.

#### Readiness Example

```json
"data_enrichment": {
  "readiness_contributors": {
    "sleep_score": 78.5,
    "hrv_score": 82.1,
    "rhr_score": 91.4,
    "temp_score": 100,
    "resp_score": 95.0,
    "oxy_score": 100
  },
  "readiness_score": 87.9
}
```

**Explanation:**

* `readiness_score`: Final normalized score (0–100). Higher = better recovery for the day.
* `readiness_contributors`: Six normalized inputs blended into the final score — sleep quality, HRV, resting HR, body temperature, respiratory rate, and SpO₂.

#### 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 Index 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": 12.4,
  "strain_traffic_light": "GREEN"
}
```

**Explanation:**

* `strain_index`: Value from **−50 to 50**
  * `≥ 0` = Recovery and parasympathetic dominance (**GREEN**)
  * `−25` to `< 0` = Mild strain (**AMBER**)
  * `< −25` = Strong physiological strain (**RED**)
* `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

> The `strain_traffic_light` tag (“GREEN”, “AMBER”, “RED”) provides an easy-to-interpret summary derived from `strain_index`.

***

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

***


---

# 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.