Is this the user's phone screen time?

No. The engagement biomarkers describe the user's time in your app only, recorded by the Sahha SDK from your app's own lifecycle events. Sahha does not see other apps.

What counts as one session?

A foreground period of your app: from the moment it comes to the foreground to the moment it goes to the background. The SDK reports these as resume and pause events, and a resume followed by a pause is one session.

Do engagement biomarkers need any permissions?

No. They come from the SDK's own lifecycle hooks, not from HealthKit or Health Connect, so every profile with the SDK installed produces them.

App sessions

What the engagement biomarkers measure

Biomarker	What it is	Unit
`app_sessions`	Number of times your app was brought to the foreground in the day	Count
`app_session_duration`	Total foreground time across those sessions	Seconds
`app_session_average_duration`	Total duration divided by session count	Seconds

Field	`app_sessions`, `app_session_duration`, `app_session_average_duration`
Unit	Count, seconds, seconds
Reported	Daily
Window	Midnight to midnight, profile local time
Wearable required	No
API	`GET /api/v1/profile/biomarker/{externalId}?categories=engagement` plus one `types` parameter per field and a date range
Webhook	`BiomarkerCreatedIntegrationEvent`. Entries update in place, upsert on `id`.

Data sources

There is one source: the Sahha SDK inside your app, on both iOS and Android. It records a resume event when your app enters the foreground and a pause event when it leaves, and on some builds a direct session event with its duration. No platform health store is involved and no permission is required.

The biomarkers describe your app, not the device. If the user also has a second app with the Sahha SDK under a different account, the two are separate profiles and separate numbers.

How Sahha calculates app sessions

Order the day’s resume and pause events by time.
Each resume followed by a pause is one session, with duration equal to the gap. Direct session events are counted as they arrive.
app_sessions is the count, app_session_duration the sum of durations, and app_session_average_duration the sum divided by the count.

A resume with no following pause, for example when the app is force-quit or the process is killed, does not produce a session. Absence means the app was not opened that day, or the SDK was not running.

Interpreting the value

Short average sessions are normal for a health app. Users open, glance at a score, and leave. A 20-second average is a healthy check-in habit, not a problem.

Session count is the retention signal. Days with at least one session, over a rolling week, is the number that predicts whether a user is still with you. Duration matters less.

The window is the profile’s local day. A midnight session lands on whichever date the resume fell in.

The engagement biomarkers are not score factors and have no trend or comparison insight. They are available alongside the health biomarkers so that engagement and health can be analysed together for the same profile.

Use cases

A health-versus-engagement view. Join daily sessions with the daily Wellbeing Score in your warehouse. Whether users open the app more on good days or bad days shapes when you should message them.

GET /api/v1/profile/biomarker/{externalId}?categories=engagement&types=app_sessions&types=app_session_duration&startDateTime=2026-08-04&endDateTime=2026-09-03

A dormancy trigger. No app_sessions for a set number of days is the trigger for a re-engagement message, and the health biomarkers tell you what to say in it.

CRM enrichment. Sessions and duration are already in the shape a CDP wants. The Customer.io and Amplitude tutorials show the pattern.

Limitations

Your app only. Not device screen time, not other apps.
Killed sessions are lost. A session with no pause event is not counted.
Depends on the SDK being initialised on app start. An app that initialises the SDK lazily records fewer sessions than it has.
Absence is not zero.

Health data for marketing and CX for how engagement and health data combine in campaigns
Data dictionary in the developer docs