Dashboard

Health Scores

Learn how to embed adaptive health scores in your app

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

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 :

Score Type
Payload Location
Frequency
Source Data Needed

🛡️ Immunity Index

Daily Summary

With every new daily payload

HRV, respiratory rate, body temperature

🫁 Respiratory Health

Daily Summary

With every new daily payload

Oxygen saturation, respiratory rate, training

🏋️‍♀️ Training Stress

Daily Summary

With every new daily payload

Deep sleep, light sleep, REM, total sleep, body temperature, HRV, RHR, Oxygen Saturation

💤 Sleep Score

Sleep Payload

With every new sleep payload

Sleep stages, HR, HRV

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.

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

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


"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


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

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

PreviousPricingNextHealth Rewards

Last updated

Was this helpful?