---
title: Trends
---


## Introduction

Trends are part of [Sahha Insights](/docs/products/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

{% data-table height=400 searchable=true badges="Category" badgeColors="score:green,factor:yellow" %}

| 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` |

{% /data-table %}

Browse our [comprehensive data dictionary](/docs/get-started/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.

{% api-example %}

{% api-panel %}
{% api-property field="id" type="UUID" description="Unique identifier for the trend" /%}
{% api-property field="type" type="string" description="Always set to trend" /%}
{% api-property field="category" type="string" description="One of score, factor, or biomarker" /%}
{% api-property field="name" type="string" description="The metric being trended (e.g., sleep)" /%}
{% api-property field="state" type="string" description="Directional movement: increasing, decreasing, or stable" /%}
{% api-property field="isHigherBetter" type="boolean" nullable=true description="Whether higher values are generally better" /%}
{% api-property field="valueRange" type="float[]" description="Range of expected values, e.g. [0.0, 1.0]" /%}
{% api-property field="unit" type="string" description="Unit of the metric (e.g., index, bpm, steps)" /%}
{% api-property field="periodicity" type="string" description="Frequency of calculation (currently weekly)" /%}
{% api-property field="trendStartDateTime" type="datetime" description="Start of the rolling window" /%}
{% api-property field="trendEndDateTime" type="datetime" description="End of the rolling window" /%}
{% api-property field="data" type="TrendData[]" description="List of entries with value and change info (4 weekly entries)" /%}
{% api-property field="createdAtUtc" type="datetime" description="UTC timestamp when the trend was calculated" /%}
{% api-property field="version" type="float" description="Version of trends" /%}
{% /api-panel %}

```json {% title="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"
}
```

{% /api-example %}

{% api-panel badge="Object" name="TrendData" description="Each entry in the data array contains:" %}
{% api-property field="id" type="UUID" description="Unique identifier for the data entry" /%}
{% api-property field="startDateTime" type="datetime" description="Start of the week for this data entry" /%}
{% api-property field="endDateTime" type="datetime" description="End of the week for this data entry" /%}
{% api-property field="value" type="float" nullable=true description="Average value for the metric in this period" /%}
{% api-property field="percentChangeFromPrevious" type="float" nullable=true description="Percent change from the previous entry's value" /%}
{% /api-panel %}

---

## Getting Started

{% action-cards %}

{% action-card icon="code" href="/docs/connect/api" title="API" description="Query trends via GET /api/v1/profile/insight/trend" /%}

{% action-card icon="bell" href="/docs/connect/webhooks" title="Webhooks" badge="Coming Soon" badgeColor="amber" description="Receive weekly trend updates automatically" /%}

{% /action-cards %}

---

## FAQ

{% faq %}

{% faq-item question="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.
{% /faq-item %}

{% faq-item question="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.
{% /faq-item %}

{% faq-item question="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.
{% /faq-item %}

{% faq-item question="Can I define my own trends or window size?" %}
Not yet. For now, all trends use a 4-week rolling window.
{% /faq-item %}

{% /faq %}

---

## Support

For assistance with Trends or the Insights product in general, reach out at [support@sahha.ai](mailto:support@sahha.ai) or join the [Sahha Slack Community](https://join.slack.com/t/sahhacommunity/shared_invite/zt-1w0fmfbvk-qUwQ83tJgXyjT9XSxJvKIw).