Health Scores

Learn how to embed adaptive health scores in your app

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

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

Sleep payload

Score	JSON field	Frequency	Source Data Needed
💤 Sleep Score	sleep_score	With every new sleep payload	Sleep stages (REM, deep, light, total), RHR, HRV, body temperature, SpO₂
💤 Sleep Score V2	sleep_score_v2	With every new sleep payload	Sleep stages, average HR, body temperature, HRV (14-day baseline)
🌅 Readiness	readiness_score	With every new sleep payload	Sleep stages, RHR (30-day), HRV (30-day), body temperature, respiratory rate, SpO₂
🫁 Respiratory Health V2	respiratory_score_v2	With every new sleep payload	SpO₂, respiratory rate (14-day baseline)

Activity payload

Score	JSON field	Frequency	Source Data Needed
🔥 Activity Strain	strain_score	With every new activity payload	Average heart rate, activity duration, 14-day max HR
⚡ Activity Efficiency	efficiency_score	With every new activity payload	Average speed, average heart rate, 14-day max HR
❤️ Activity RCRS	rcrs_score	With every new activity payload	Average heart rate, activity duration, 30-day max HR
📈 Activity TRIMP	trimp_score	With every new activity payload	Average heart rate, activity duration, 30-day max HR

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

"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

"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

"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

"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

---