Trends | Sahha Docs

Q: What if higher value isn't always better?

That's why we include the isHigherBetter field. It allows consumers to interpret whether a trend is good or bad in the context of the metric.

Introduction

Trends are part of Sahha Insights. They are designed to detect and communicate directional change in a score, factor, or biomarker over time. Rather than just looking at today's value, a trend reveals how that value has evolved over the last few weeks — is it going up? Down? Staying the same? And by how much?

List of Trends

Name	Category	Description	Unit	valueRange	isHigherBetter
wellbeing	score	Holistic health combining sleep and activity	index	`[0, 1]`	`true`
activity	score	Physical activity and movement levels	index	`[0, 1]`	`true`
sleep	score	Overall sleep quality	index	`[0, 1]`	`true`
readiness	score	Body's recovery state and preparedness for exertion	index	`[0, 1]`	`true`
mental_wellbeing	score	Mental wellbeing state based on behavioral patterns	index	`[0, 1]`	`true`
sleep_duration	factor	Total time spent asleep	index	`[0, 1]`	`true`
sleep_regularity	factor	Consistency of sleep schedule	index	`[0, 1]`	`true`
sleep_continuity	factor	Uninterrupted sleep with minimal awakenings	index	`[0, 1]`	`true`
sleep_debt	factor	Accumulated sleep deficit	index	`[0, 1]`	`true`
circadian_alignment	factor	Alignment with natural sleep-wake cycle	index	`[0, 1]`	`true`
physical_recovery	factor	Deep sleep phase duration	index	`[0, 1]`	`true`
mental_recovery	factor	REM sleep phase duration	index	`[0, 1]`	`true`
steps	factor	Daily step count	index	`[0, 1]`	`true`
active_hours	factor	Hours with significant physical activity	index	`[0, 1]`	`true`
active_calories	factor	Calories burned during activity	index	`[0, 1]`	`true`
intense_activity_duration	factor	Time spent in high-intensity activity	index	`[0, 1]`	`true`
floors_climbed	factor	Vertical movement measurement	index	`[0, 1]`	`true`
extended_inactivity	factor	Prolonged sedentary periods	index	`[0, 1]`	`true`
activity_regularity	factor	Consistency of daily activity patterns	index	`[0, 1]`	`true`
resting_heart_rate	factor	Heart rate during rest	index	`[0, 1]`	`true`
heart_rate_variability	factor	Variation in time between heartbeats	index	`[0, 1]`	`true`
walking_strain_capacity	factor	Capacity to do low-intensity activities	index	`[0, 1]`	`null`
exercise_strain_capacity	factor	Capacity to do high-intensity exercises	index	`[0, 1]`	`null`

Browse our comprehensive data dictionary to view all available outputs beyond just trends.

How It Works

Trends analyze the last 4 complete weeks of data on a rolling basis. For each eligible metric (like sleep score, activity score, sleep duration, etc.), Sahha computes a weekly average, compares it to previous weeks, and classifies the directional movement as one of:

increasing: meaningful upward movement
decreasing: meaningful downward movement
stable: no significant change

The overall trend state is determined by the percent change in the latest week's data compared to the previous week.

Trends are generated every week, and include:

A rolling 4-week time window
Percent change calculations between each week
A state label (increasing/decreasing/stable)
Range and unit metadata

Output Schema

Each trend is scoped to a single profile and metric. It includes the past 4 full weeks of data and is calculated at the end of each week on a rolling basis.

id UUID

Unique identifier for the trend

type string

Always set to trend

category string

One of score, factor, or biomarker

name string

The metric being trended (e.g., sleep)

state string

Directional movement: increasing, decreasing, or stable

isHigherBetter boolean nullable

Whether higher values are generally better

valueRange float[]

Range of expected values, e.g. [0.0, 1.0]

unit string

Unit of the metric (e.g., index, bpm, steps)

periodicity string

Frequency of calculation (currently weekly)

trendStartDateTime datetime

Start of the rolling window

trendEndDateTime datetime

End of the rolling window

data TrendData[]

List of entries with value and change info (4 weekly entries)

createdAtUtc datetime

UTC timestamp when the trend was calculated

version float

Version of trends

Example Response

JSON

{
	"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"
}

Object

TrendData

Each entry in the data array contains:

id UUID

Unique identifier for the data entry

startDateTime datetime

Start of the week for this data entry

endDateTime datetime

End of the week for this data entry

value float nullable

Average value for the metric in this period

percentChangeFromPrevious float nullable

Percent change from the previous entry's value

Getting Started

API

Query trends via GET /api/v1/profile/insight/trend

Webhooks Coming Soon

Receive weekly trend updates automatically

FAQ

How is the trend state (increasing/decreasing/stable) determined? +

Sahha uses relative percent change and a metric-specific significance threshold to determine if the movement is meaningful.

What if higher value isn't always better? +

That's why we include the isHigherBetter field. It allows consumers to interpret whether a trend is good or bad in the context of the metric.

What if there is missing/no data? +

That week is skipped in the 4-week window. At least two valid weeks are needed to calculate a trend.

Can I define my own trends or window size? +

Not yet. For now, all trends use a 4-week rolling window.

Support

For assistance with Trends or the Insights product in general, reach out at support@sahha.ai or join the Sahha Slack Community.