Updated 1 week ago Guides

Sahha Comparisons Explained

A builder’s guide to Sahha Comparisons—how daily benchmarks work, what metrics are supported, and how to use global, demographic, and baseline comparisons in your product.

Comparisons provide daily context for scores and biomarkers by benchmarking a user’s value against:

  • Global population averages
  • Demographic cohorts (e.g., similar age and gender)
  • Personal baseline (the user’s own historical average, typically the last 30 days)

Comparisons answer:

  • “Is this value typical or unusual?”
  • “How do they compare to peers?”
  • “Are they above/below their own baseline?”

Key Takeaways

  • Daily context layer: comparisons are calculated daily and designed to contextualize today’s values.
  • Three lenses: global, demographic, and baseline (personal history).
  • Percentiles + states: includes percentile ranks (where applicable) and a simple state label.
  • Great for explainability: perfect for “how am I doing?” UI and for prioritizing interventions.

Spec

ItemValue
Insight typecomparison
CadenceDaily
Categoriesscore and biomarker
Reference groupsglobal, demographic, baseline (last 30 days)
OutputReference values + percentile + difference + state label
RetrievalAPI (profile token) and API (account token by externalId)

How Comparisons Work

For each eligible metric, Sahha produces three comparison points:

  1. Global: compared to global population averages
  2. Demographic: compared to people with similar characteristics (e.g., age and gender)
  3. Baseline: compared to the individual’s historical average over the last 30 days

Each comparison can include:

  • reference group average
  • percentile position (not applicable for baseline)
  • absolute and percentage differences vs the user’s value
  • a descriptive state label: very_low, low, average, high, very_high

Output Schema (What You Get)

Each comparison is scoped to a single profile + metric.

Common fields:

  • type: always comparison
  • category: score or biomarker
  • name: metric being compared (e.g., readiness)
  • value: the user’s value
  • unit: index, bpm, count, etc.
  • isHigherBetter: whether higher values are generally better
  • periodicity: daily
  • startDateTime / endDateTime: daily window
  • data: array of comparison entries (global/demographic/baseline)
  • createdAtUtc: time calculated

Example response:

{
  "type": "comparison",
  "category": "score",
  "name": "readiness",
  "value": 0.75,
  "unit": "index",
  "isHigherBetter": true,
  "periodicity": "daily",
  "startDateTime": "2025-04-02T00:00:00+04:00",
  "endDateTime": "2025-04-02T23:59:59+04:00",
  "data": [
    {
      "type": "demographic",
      "value": 0.71,
      "percentile": 58,
      "state": "average",
      "properties": { "ageMin": 30, "ageMax": 44, "gender": "female" }
    },
    { "type": "global", "value": 0.78, "percentile": 42, "state": "average" },
    {
      "type": "baseline",
      "value": 0.84,
      "percentile": null,
      "difference": -0.09,
      "properties": { "windowDays": 30 }
    }
  ],
  "createdAtUtc": "2025-04-06T09:30:00Z"
}

What Comparisons Cover (Eligible Metrics)

Comparisons are available for a defined set of scores and biomarkers, including:

Scores (examples)

  • sleep
  • activity
  • readiness
  • wellbeing
  • mental_wellbeing

Biomarkers (examples)

  • steps
  • sleep_duration
  • heart_rate_resting
  • heart_rate_variability_sdnn
  • heart_rate_variability_rmssd
  • vo2_max

For the full supported list, refer to the Comparisons page.

How to Use Comparisons in Your Product

1) “How am I doing?” cards (fastest value)

Examples:

  • “Your sleep score is high vs peers”
  • “Your resting heart rate is low vs global average”
  • “You’re below baseline on steps today”

2) Triage and prioritization

Use comparison states to prioritize interventions:

  • very_low or low vs baseline → highest priority
  • average → maintain
  • high / very_high → celebrate or progress

A strong decision pattern:

  • Trend says direction
  • Comparison says how unusual
  • Together they give robust triggers

Example:

  • Sleep trend decreasing + sleep comparison low vs baseline → recovery journey
  • Activity trend increasing + activity comparison high → progression plan

Implementation Suggestions for your Products

  1. Use state labels in UX

    • very_low/low/average/high/very_high is easier than raw percentiles for most users.

  2. Use baseline for personalization

    • Baseline is often the most actionable reference (it’s “you vs you”).

  3. Use demographic/global for motivation (carefully)

    • Great for context, but avoid shame-based framing.

  4. Store daily comparisons for reporting

    • Persist one record per (metric + day) if you want historical “benchmark charts.”

Getting Started

API

  • Profile token: GET /api/v1/profile/insight/comparison
  • Account token: GET /api/v1/profile/insight/comparison/{externalId}

FAQ

Why is baseline percentile null?

Baseline is “you vs you,” so percentile isn’t applicable. Comparisons instead provide differences vs your historical average.

What demographics are used?

Comparisons include demographic properties in the response (e.g., age range and gender) for transparency.

Can I customize the baseline window?

Not currently. Baseline comparisons use a standard window (documented as 30 days).

References