Sync Apple Health Data to MQTT

Publish health exports as JSON to a topic on your MQTT broker.

Important — automation limitations: Your device must be unlocked to read health data, and iOS does not guarantee background runs at your chosen frequency. Review Automation Limitations before relying on automatic exports.

Open the automation

Open Export → Automated on iPhone, or Automations in the iPad sidebar. Select New Automation, or open an existing automation to edit it.

Name, status, and notifications

Enter a name that identifies this automation. Enabled allows automatic runs; leave it off until you are ready.

Choose any run notifications you want:

• Notify on Cache Update reports that export data was prepared.
• Notify When Run reports a successful publish to the broker.

Allow notifications when prompted. These notifications report activity; they do not schedule a run.

Set up the connection

1. Choose MQTT as the Automation Type.
2. Enter your broker’s hostname or IP address and port. The default port is 1883.
3. Enter the Topic, for example health/metrics.
4. Set a unique Client ID for each automation and enter a username and password if required by the broker.

The broker must be reachable from your device. Subscribers must use the exact topic, including capitalization. Reusing a client ID can cause broker connections to replace one another.

Data Type Settings

Select one Data Type for this automation: Health Metrics, Workouts, Symptoms, ECG, Heart Rate Notifications, State of Mind, Cycle Tracking, or Medications. State of Mind requires iOS 18 or later; Medications requires iOS 26 or later and separate medication access.

Health metrics

Choose Health Metrics, then open Select Health Metrics and select the measurements you need.

To limit readings to particular apps or devices, open Preferred Sources, choose a metric, and select its sources. All allows every source that has not been excluded. Use Excluded Sources to ignore a source across this automation’s health metrics. Exclusions take precedence; an unselected source is not substituted when a preferred source has no data. Select Save to apply the source choices or Cancel to discard them.

Workouts

Choose Workouts to export workout records. Include Route Data adds available route points to JSON workout data. It does not create separate GPX uploads.

For Version 2, turn on Include Workout Metrics to add readings such as heart rate, active energy, and steps. Choose Minutes or Seconds for workout-metric Time Grouping; seconds produce more detail and larger exports. Version 1 always includes workout metrics.

Export Settings

MQTT publishes JSON only. Messages use QoS 0 for foreground publishing and QoS 1 for background publishing. Messages are not retained.

Export Version

Choose Version 2 for the current data structure. Use Version 1 when an existing workflow depends on the older format.

Date Range

Selection	Data included
Default	The previous day and today up to the run time
Since Last Sync	Since the previous sync up to the run time
Today	Today up to the run time
Yesterday	The previous full day
Previous 7 Days	The previous seven full days

Summarize Data and Time Grouping

For JSON + Health Metrics, turn Summarize Data on to combine readings into time groups, or off for individual readings where available. The summary depends on the metric—for example, steps are totaled and weight readings are averaged. CSV health-metric exports use summarized data.

When Time Grouping is available, choose how much detail to keep. Hourly or daily groups produce fewer rows than minute or second groups. Available choices depend on the date range and format. Workout time grouping is configured separately under Workouts.

Schedule Reminders

If you want a prompt to unlock and open the app, turn on Enable Reminders. Choose Hourly, Every Day, or Selected Days, then set the minute, time, and days as applicable. Allow notification access when prompted; if access is denied, use Open Notification Settings.

A reminder does not run the automation or confirm a successful sync. Tap it to open the automation, or use Open & Sync on the notification to request a run. The automation must be enabled; a reminder may still appear after a successful background run. Reminder changes apply when you save.

Sync Frequency and save

Choose a number and Minutes, Hours, Days, or Weeks under Sync Frequency—for example, every 15 minutes. This is a desired background cadence, not a guaranteed schedule.

Your device must be unlocked when health data is read. Enable Background App Refresh for Health Auto Export and turn off Low Power Mode for automatic runs. iOS may still delay runs when the device has been inactive or system resources are limited.

Turn on Enabled when you are ready for automatic runs, then select Update to save the automation. You can upload a selected date range immediately using the steps below.

Export historical or missed data

Use Manual Upload when you first set up the automation to export historical data, or later to cover dates missed by automatic syncing. You can also use it to check your setup.

1. Connect an MQTT subscriber to your broker and subscribe to the configured topic.
2. In Health Auto Export, open the automation and select Manual Upload under Export Existing Data.
3. Set the Start and End dates, then select Begin Export.
4. Check the received JSON and its dates.

The payload follows the JSON export format. For example:

{
  "data": {
    "metrics": [
      {
        "name": "step_count",
        "units": "count",
        "data": [{"date": "2024-02-06 00:00:00 -0800", "qty": 8500}]
      }
    ]
  }
}

Troubleshooting

• Connection failed: Check the host, port, network access, and broker connection requirements.
• Authentication failed: Check credentials and permission to publish to the topic.
• No message: Confirm the subscriber uses the same broker and exact topic, then review Activity Logs.
• Message too large: Select fewer metrics, a shorter range, or coarser time grouping.

Open the automation and select View Activity Logs to review a run. Warnings flag potential issues such as slow data retrieval; errors identify failed steps. For help reporting an issue, see Getting Help.