Updated 1 week ago Guides

Sahha Trends Explained

A builder’s guide to Sahha Trends—how trends are calculated, what metrics are supported, and how to use trend states to drive engagement and coaching.

Trends detect and communicate directional change in a score, factor, or biomarker over time—so you can build “what’s changing?” logic without manually computing rolling windows.

A trend answers:

  • Is this metric increasing, decreasing, or stable?
  • Over the last few weeks, by how much?

Key Takeaways

  • Trends are weekly, not daily: they summarize the last 4 complete weeks of data using weekly averages.
  • Simple state labels: increasing, decreasing, or stable.
  • Built for action: ideal for nudges, check-ins, retention journeys, and coach dashboards.
  • Handles missing data: weeks without data can be skipped; at least two valid weeks are needed to compute a trend.

Spec

ItemValue
Insight typetrend
CadenceWeekly
WindowRolling last 4 complete weeks
InputsScore, Factor, Biomarker
OutputState + weekly data points + percent change
RetrievalAPI (profile token) and API (account token by externalId)

Sahha Trends:

  1. Analyze the last 4 complete weeks on a rolling basis
  2. Compute a weekly average for each eligible metric
  3. Compare the latest week to the prior week
  4. Assign a state:
    • increasing (meaningful upward movement)
    • decreasing (meaningful downward movement)
    • stable (no significant change)

Trend state is determined using relative percent change and a metric-specific significance threshold (to avoid noise being labeled as “change”).

Output Schema (What You Get)

Each trend is scoped to a single profile + metric and includes the 4-week series.

Common fields:

  • type: always trend
  • category: score, factor, or biomarker
  • name: metric name (e.g., sleep)
  • state: increasing, decreasing, stable
  • isHigherBetter: whether higher values are generally better
  • valueRange: expected range (e.g., [0.0, 1.0])
  • unit: index, bpm, steps, etc.
  • periodicity: currently weekly
  • trendStartDateTime / trendEndDateTime: rolling window bounds
  • data: 4 weekly entries (value + percentChangeFromPrevious)
  • createdAtUtc: time calculated

Example response:

{
  "type": "trend",
  "category": "score",
  "name": "sleep",
  "state": "increasing",
  "isHigherBetter": true,
  "valueRange": [0.0, 1.0],
  "unit": "index",
  "periodicity": "weekly",
  "trendStartDateTime": "2023-05-01T00:00:00+05:00",
  "trendEndDateTime": "2023-05-29T00:00:00+05:00",
  "data": [
    { "startDateTime": "2023-05-01", "value": 0.65, "percentChangeFromPrevious": null },
    { "startDateTime": "2023-05-08", "value": 0.75, "percentChangeFromPrevious": 0.15 },
    { "startDateTime": "2023-05-15", "value": 0.71, "percentChangeFromPrevious": -0.05 },
    { "startDateTime": "2023-05-22", "value": 0.78, "percentChangeFromPrevious": 0.1 }
  ],
  "createdAtUtc": "2023-05-30T09:30:00Z"
}

Trends can be produced for categories such as:

  • Scores: sleep, activity, readiness, wellbeing, mental_wellbeing
  • Factors: commonly includes sleep and activity drivers (e.g., sleep_duration, sleep_regularity, sleep_debt, circadian_alignment, steps, active_hours, extended_inactivity, floors_climbed, and more)
  • Biomarkers: depends on availability and eligibility

For the full live list, refer to the Trends page (it lists category/name/unit/range/isHigherBetter).

1) Weekly check-ins (high-performing UX)

  • If trend is increasing: celebrate momentum
  • If trend is stable: reinforce consistency
  • If trend is decreasing: offer a low-friction re-entry plan

2) Engagement pacing

Trends help you avoid overreacting to single bad days:

  • Don’t fire an intervention from one low score
  • Do respond when the trend is decreasing (pattern-level change)

3) Coaching / care escalation (when appropriate)

Use trend + a safeguard:

  • “decreasing” for 2 consecutive weeks
  • AND a comparison below baseline or below demographic (if you use comparisons)
  • THEN escalate into a stronger journey

Implementation Suggestions for your Products

  1. Use trend state for decisions, not raw percent changes

    • The state already accounts for significance thresholds.

  2. Keep your rules trend-first

    • Example: only intervene when a trend is decreasing (not on a single daily score).

  3. Store the 4-week series for explainability

    • Use the data array to power simple charts and “here’s what changed” UI.

  4. Handle missing weeks gracefully

    • If an insight isn’t available, treat it as “not enough history.”

Getting Started

API

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

FAQ

Weekly averages reduce noise and better reflect behavior change rather than day-to-day variance.

Can I customize the window size?

Not currently. Trends use a rolling 4-week window.

What if higher isn’t always better?

Use isHigherBetter to correctly interpret directionality in UX and automation rules.

References