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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tryterra.co/faq/help-topics/data-api-sdk/mobile-sdk-setup-permissions-and-crashes/apple-health-sdk-overview-capabilities.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.