> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/faq/help-topics/data-api-sdk/mobile-sdk-setup-permissions-and-crashes/apple-health-sdk-overview-capabilities.md).

# How does the Apple Health SDK work?

Apple Health has no server API. It is read on-device through the [iOS SDK](https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources/ios-swift) via HealthKit.

**Data types**: a wide set is supported, including steps, sleep, resting HR, workouts, calories, weight, HRV and nutrition.

**History**: you specify the historical date range when requesting data, limited only by what the device retains.

**Sync**: once you enable [background delivery](https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources/ios-swift) (call `Terra.setUpBackgroundDelivery()` in your `AppDelegate`), new HealthKit data is sent to your destination **automatically**, including while the app is in the background. Delivery is triggered by iOS, so it requires the **phone to be unlocked** and a **network connection**, fires for **enabled dashboard data types only**, and still fires when the **app is killed but at a much lower frequency**. iOS controls the exact timing, so true real-time delivery is not guaranteed.

**Connection state**: per-user state arrives as `auth`, `connection_error` and `deauth` events on your [webhook](https://docs.tryterra.co/health-and-fitness-api/user-authentication/handling-authentication-events).

To **scope to workouts only**, request `WORKOUT_TYPE`, `HEART_RATE`, `CALORIES` and `EXERCISE_DISTANCE`. Enabling only Activity in the dashboard suppresses Daily, Body and Sleep. Keep **Include Samples** ticked, or `hr_samples` are stripped.

`hr_samples` carry a per-sample timestamp, `bpm` and `timer_duration_seconds`, the same shape across providers. `metadata.type` is always Terra's unified integer enum, identical across every provider, so you can map straight off the integer.

The native iOS SDK can also be wrapped in your own Capacitor plugin. It needs the HealthKit capability and the relevant `Info.plist` usage strings.