Updated 1 week ago Guides

Sahha Insights Explained

A builder’s guide to Sahha Insights—what they are, what they cover, and how to use trends and comparisons to drive engagement, coaching, and reporting.

Insights are higher-order analytics that turn point-in-time scores and biomarker values into actionable signals of change and context—so you can build engagement, coaching, reporting, and progress tracking without rolling your own analytics layer.

Instead of asking: “What is today’s value?”, insights answer: “What’s changing?” and “How does this compare?”

Key Takeaways

  • Insights sit above metrics: they analyze Sahha’s existing scores, factors, and biomarkers to surface patterns.
  • Use insights to drive actions: nudges, rewards, interventions, retention flows, summaries, and reports.
  • Two insight types are live today: Trends (directional change) and Comparisons (benchmark context).
  • Builder-friendly by design: minimal setup, consistent schema, and ready-to-store outputs.

What Insights Cover

Insights currently focus on two foundational “builder questions”:

  1. Change over time

    • Is this metric increasing, decreasing, or stable over recent weeks?

  2. Context and benchmarking

    • Is this value typical or unusual compared to a baseline or a reference population?

Available Insights

  • Trends (Live): Detect directional change over time (increasing / decreasing / stable)
  • Comparisons (Live): Compare values to personal or population benchmarks

Coming Soon (Roadmap)

  • Streaks: Track consistency—consecutive days meeting goals
  • Milestones: Celebrate achievements and progress markers
  • Associations: Discover correlations between behaviors and outcomes
  • Alerts: Trigger notifications when metrics cross thresholds

Spec

ItemValue
ProductInsights
Current insight typesTrends, Comparisons
InputsScores, Factors, Biomarkers
Output styleNormalized insight objects (easy to store + act on)
RetrievalAPI (profile token) and API (account token by externalId)
WebhooksTrend + Comparison webhooks referenced as “Coming Soon” in product docs

How Insights Work (Conceptually)

Insights analyze the data Sahha already produces:

  • Scores (e.g., sleep, activity, readiness, wellbeing, mental wellbeing)
  • Factors (explainable drivers inside scores)
  • Biomarkers (daily aggregates like steps, sleep duration, RHR, HRV)

They then emit an “insight object” you can treat like a product-ready signal:

  • store it as a user attribute (latest trend state, latest comparison state)
  • use it to trigger automation (nudges, messages, in-app prompts)
  • use it for reporting (weekly summaries, coach dashboards)

When to Use Insights (vs raw metrics)

Use Insights when you need decisions

  • “Is sleep getting worse over the last month?”
  • “Are they below baseline?”
  • “Is this user high/low compared to their peers?”
  • “Which users should receive a recovery intervention this week?”

Use raw metrics when you need display values

  • “Show today’s step count”
  • “Show last night’s sleep duration”
  • “Show HRV and RHR values”

A good default is: metrics for display, insights for decisions.

Practical Product Use Cases

1) Lifecycle messaging

  • Trend turns into “what’s changing”
  • Comparison turns into “how unusual is it”

Example:

  • If sleep trend is decreasing AND sleep comparison is very_low → send a supportive recovery journey

2) In-app coaching

  • Trend → determine direction and momentum
  • Comparison → determine whether to push, maintain, or de-escalate

Example:

  • Activity trend increasing + comparison high → celebrate and recommend progression
  • Activity trend decreasing + comparison low → suggest a low-friction restart plan

3) Reporting and summaries

  • Trends produce clean weekly storylines
  • Comparisons produce instant context (“above baseline”, “below peers”)

Implementation Suggestions for your Products

  1. Store the “latest insight per metric”

    • Keep one record per (insight type + metric name + category) as the current state.

  2. Separate “decision logic” from “display logic”

    • Decisions: use insight states (e.g., decreasing, very_low)
    • Display: use the underlying scores/biomarkers for values and charts

  3. Prefer multi-signal rules

    • Use trend + comparison + a simple guardrail (e.g., 2-week persistence) to avoid noisy interventions.

  4. Design for missing data

    • Some profiles won’t have enough history. Treat missing insights as “insufficient data” (not failure).

Getting Started

  • Trends API: GET /api/v1/profile/insight/trend (profile token) or GET /api/v1/profile/insight/trend/{externalId} (account token)
  • Comparisons API: GET /api/v1/profile/insight/comparison (profile token) or GET /api/v1/profile/insight/comparison/{externalId} (account token)

Tip: Use the profile-token endpoints for client apps and the {externalId} endpoints for server-side batch jobs.

FAQ

Are insights real-time?

Insights update on the cadence of their type (weekly for trends, daily for comparisons). Underlying data still arrives continuously, but insights summarize it into builder-ready signals.

Do I need to configure anything?

Insights are designed as “zero setup” outputs—once you’re ingesting Sahha data, you can query insights for eligible metrics.

What should I do with insights?

Treat them as signals that drive product logic: messaging, nudges, rewards, check-ins, and interventions.

References