Exfero Health export format
This document describes the files Exfero Health writes: mainly the JSON and JSON Lines formats, which are meant for other programs, and briefly CSV and Markdown. It's for anyone who reads the exports with a script or dashboard.
- Current version: schema version 8.
- Machine-readable definition:
export.schema.json(JSON Schema, draft 2020-12). - Examples:
example-export.jsonand the same export as JSON Lines,example-export.jsonl, written by Exfero Health's own formatters.
Tests in the app check that the schema, the example and the data type table below match what the app writes.
Compatibility
schemaVersion changes whenever the structure changes: a field is added, renamed or removed, or a field can hold new values. Readers should check it and refuse or warn about versions they don't know. Files without schemaVersion are version 1. The version history lists every change.
Within one version, every record has the same keys. Missing values are null, never left out.
File names
File names come from the template's pattern. New templates use {name}_{start}_{end}, such as Sleep & Breathing_2026-11-08_2026-11-14.json; templates made with earlier versions (when the app was called HealthPort) keep HealthPort_{start}_{end} until you change it on the Where page. The placeholders are {name} (the template name, with characters a file name can't hold replaced by -, or ExferoHealth when no letter or digit is left), {start} and {end} (the first and last day of the range, such as 2026-11-08), {from} and {to} (the exact start and end of the range, such as 2026-11-07_1200 and 2026-11-15_0000), {date} (the export day) and {time} (the export time, such as 0915), all in the iPhone's time zone. {to} is the exclusive end, so a range that ends at midnight ends at 0000 the next day. The extension follows the format: .json, .jsonl (JSON Lines), .csv or .md. If the folder already holds a file with that name, the template either replaces it or adds a two-digit number counting up from _01: Sleep & Breathing_2026-11-08_2026-11-14_01.json, then _02 and so on.
Top level
| Field | Type | Description |
|---|---|---|
schemaVersion |
integer | The format version, currently 8. |
generatedAt |
timestamp | When the export was made. |
timeZone |
string | The exporting iPhone's time zone, as an IANA identifier such as Europe/Amsterdam. |
range |
object | The period the export covers: start and end (exclusive), both timestamps. See Date range. |
recordCount |
integer | The number of items in records. |
records |
array | The samples, sorted by startDate. See Records. |
deleted |
array | Samples deleted from Health since the previous export. See Since last export. |
gaps |
array | Possible gaps in the data. See Gaps. |
gapCheck |
object or null |
What the gap check looked at. See Gaps. |
Timestamps are ISO 8601 in UTC with milliseconds, such as 2026-11-13T22:41:00.000Z. Use timeZone (on a record when present, otherwise the top-level one) to show local times.
Date range
range follows the template's date rule. With Start data at noon the day before, it starts at 12:00 the day before the first day, so the first night is complete: a week then runs from, for example, 2026-11-07T11:00:00.000Z (noon in Amsterdam) to the end of the last day.
Records
| Field | Type | Description |
|---|---|---|
uuid |
string | HealthKit's ID for the sample, in upper case. It's the same in every export, so use it to remove duplicates when exports overlap. |
type |
string | The data type, such as heartRate. See the data type table. |
value |
number | The value in unit. For category data and workouts: the duration in minutes. |
unit |
string | HealthKit's unit syntax, such as count/min. Each type always uses the same unit. |
categoryValue |
string or null |
For category data, HealthKit's name for the value, such as asleepCore. For workouts, the activity type, such as running. null for quantities. |
startDate |
timestamp | When the sample starts. |
endDate |
timestamp | When it ends; the same as startDate for instant measurements. |
timeZone |
string or null |
The time zone the sample was recorded in, when HealthKit knows it (sleep samples usually have one). |
source |
string | The name of the app or device that recorded it. The user can rename devices, so don't rely on it. |
sourceBundleId |
string or null |
The source's bundle identifier, which stays the same when the device is renamed. |
deviceModel |
string or null |
The hardware model, such as Watch7,3 or iPhone18,2. |
attributes |
object | Extra numbers for some types (below); {} otherwise. |
Values
- Quantities (kind
quantityin the table) are in the listed unit. Percentages (%) are 0–100, not fractions. Breathing disturbances are a nightly rate per hour (count/hr), although HealthKit stores them as a plain count. Workout effort (appleEffortScore) is a rating from 1 to 10. - Category data (kind
category) has the duration in minutes asvalue, computed from the exported millisecond timestamps, so it equalsendDateminusstartDate. - Workouts (
typeworkout) have the duration in minutes asvalueand the activity incategoryValue.
Category values
type |
categoryValue |
|---|---|
sleepAnalysis |
inBed, asleepUnspecified, awake, asleepCore, asleepDeep, asleepREM |
appleStandHour |
stood, idle |
menstrualFlow |
unspecified, light, medium, heavy, none |
ovulationTestResult |
negative, luteinizingHormoneSurge, indeterminate, estrogenSurge |
cervicalMucusQuality |
dry, sticky, creamy, watery, eggWhite |
sleepApneaEvent, intermenstrualBleeding |
always null |
workout |
the activity type, named after HealthKit's HKWorkoutActivityType cases: running, walking, cycling, traditionalStrengthTraining, highIntensityIntervalTraining, yoga and so on; activity<number> for types Exfero Health doesn't name |
A value Exfero Health doesn't recognise is written as unknown(<number>).
Attributes
type |
Key | Meaning |
|---|---|---|
workout |
activeEnergyKcal |
Active energy burned, in kcal. |
workout |
distanceKm |
Distance, in km. |
workout |
averageHeartRate |
Average heart rate, in beats per minute. |
menstrualFlow |
cycleStart |
1 if this sample starts a cycle, 0 if not. |
Keys only appear when HealthKit has the value; a workout without distance has no distanceKm.
Since last export
With the Since last export rule, an export holds what Health received since the template's previous saved export, whatever the samples' own times. This means:
- Late arrivals are included. A sample that synced late, after the previous export, appears in the next one even though its
startDateis older. Sorecordscan contain samples from beforerange.start. - Nothing is exported twice, apart from overlaps with exports made with other rules; use
uuidto remove those. - Nothing is lost when an export runs late or is skipped; Exfero Health only moves on after a file was saved.
deletedlists samples deleted from Health since then, each withuuidandtype, so readers can remove them too.- A first export (and a type added to the template later) starts with the last 7 days; then
rangecovers those 7 days.
With other rules deleted is always empty.
Gaps
gaps lists what looks missing or unusual, so readers don't mistake "not measured" for "nothing happened". Every gap has type, kind, start, end and minutes.
kind |
Meaning | start and end |
|---|---|---|
noData |
A day or night without any data for a type that normally has data. | The day (midnight to midnight) or night (noon to noon, with the noon option). |
duringSleep |
Over minimumSleepGapMinutes without samples of a frequently measured type while asleep, on nights that overlap range. |
The last sample (or start of sleep) before the stretch and the first one after it. |
unstagedSleep |
A night with sleep recorded only as asleepUnspecified, without core, deep or REM stages. |
The night. |
shortSleep |
A night with less than shortSleepMinutes asleep; minutes holds the time asleep. |
The night. |
minutes is null for every kind except shortSleep.
What gets checked
gapCheck says what was judged, so a type without gaps is known to be complete only if it's listed:
| Field | Description |
|---|---|
periods |
days (midnight to midnight) or nights (noon to noon, when the range starts at noon the day before). |
missingDataMetrics |
Types checked for noData. A type is checked when it has data on at least half of the complete periods from its first data on; earlier periods don't count, as the feature may have been off. |
duringSleepMetrics |
Types checked for duringSleep: those measured on average at least every frequentSpacingMinutes while asleep. Rarely measured types such as blood oxygen usually aren't listed. |
minimumSleepGapMinutes |
The shortest stretch during sleep that counts as a gap (60). |
frequentSpacingMinutes |
The typical spacing during sleep up to which a type counts as frequently measured (15). |
shortSleepMinutes |
Nights with less time asleep are shortSleep (300). |
Only complete periods inside range and before the export time are checked: the current day is still being recorded. "Asleep" means sleep stages starting with asleep, taken from the export's own sleepAnalysis records; time in bed and awake don't count. Night-based checks (unstagedSleep, shortSleep) always use nights from noon to noon. gapCheck is null if the check didn't run.
Reading exports
- Check
schemaVersionbefore reading. - Remove duplicates by
uuid, especially when exports overlap. - With Since last export, keep processed files' samples and apply
deleted; don't assume a file holds only samples insiderange. - Identify sources by
sourceBundleId, notsource. - Convert times with the record's
timeZonewhen present, otherwise the top-leveltimeZone. - Read
gapChecktogether withgaps.
JSON Lines
A JSON Lines export (.jsonl, see jsonlines.org) holds the same information as a JSON export, with one compact JSON object per line, so it can be read line by line without loading the whole file. Lines end with a line feed, including the last one.
Each line starts with entry, which says what it holds:
entry |
Fields | Lines |
|---|---|---|
export |
The top-level fields without records, deleted and gaps. |
Always the first line, exactly once. |
record |
The record fields. | One per record, sorted by startDate. |
deleted |
uuid and type, as in deleted. |
One per deleted sample. |
gap |
The gap fields. | One per gap. |
Apart from entry, keys are sorted, as in JSON. schemaVersion on the first line has the same meaning as in JSON; each line other than the first validates against the matching definition in export.schema.json once entry is removed.
{"entry":"export","gapCheck":{…},"generatedAt":"2026-11-14T09:15:00.000Z","range":{…},"recordCount":4,"schemaVersion":8,"timeZone":"Europe/Amsterdam"}
{"entry":"record","attributes":{},"categoryValue":null,…,"type":"heartRate","unit":"count/min","uuid":"0A9B8C7D-…","value":58}
{"entry":"deleted","type":"heartRate","uuid":"5B6C7D8E-…"}
{"entry":"gap","end":"2026-11-13T05:40:00.000Z","kind":"duringSleep","minutes":null,"start":"2026-11-13T02:10:00.000Z","type":"heartRate"}
CSV and Markdown
CSV follows RFC 4180, with CRLF line endings and one row per record. The columns are type, value, unit, category_value, start_date, end_date, time_zone, source, source_bundle_id, device_model, uuid and attributes, with the same meaning as the JSON fields. Empty cells stand for null. attributes holds key=value pairs separated by ;. Text that a spreadsheet would run as a formula (starting with =, +, -, @, a tab or carriage return) starts with an apostrophe. CSV has no deleted, gaps or gapCheck.
Markdown is a report for people: the export's details, possible gaps, a summary table per metric (count, minimum, maximum, average, total), then a table of every record per metric. Its layout isn't meant for parsing.
Version history
| Version | Change |
|---|---|
| 1 | No schemaVersion field; whole-second timestamps. |
| 2 | Added uuid, sourceBundleId, deviceModel, record timeZone, top-level timeZone and sleep data; percentages became 0–100. |
| 3 | Timestamps gained milliseconds; breathing disturbances changed from count to count/hr. |
| 4 | Added attributes (workouts, cycle start) and 38 more data types, including workouts and cycle tracking. |
| 5 | Added deleted; Since last export uses what Health received. |
| 6 | Added gaps with kinds noData and duringSleep. |
| 7 | Added gap kinds unstagedSleep and shortSleep, the gap field minutes, and gapCheck. |
| 8 | Added 15 workout detail types: cycling speed, power, cadence and FTP; rowing, paddle sports, skating and cross-country skiing distance and speed; workout effort; underwater depth and water temperature. |
Data types
All 75 types Exfero Health exports, with their type and unit. Kind quantity means a measured value in unit; category and workout have the duration in minutes as value.
| Category | type |
Name | unit |
Kind |
|---|---|---|---|---|
| Activity | stepCount |
Steps | count |
quantity |
| Activity | distanceWalkingRunning |
Walking + Running Distance | km |
quantity |
| Activity | flightsClimbed |
Flights Climbed | count |
quantity |
| Activity | activeEnergyBurned |
Active Energy | kcal |
quantity |
| Activity | basalEnergyBurned |
Resting Energy | kcal |
quantity |
| Activity | appleExerciseTime |
Exercise Minutes | min |
quantity |
| Activity | appleStandTime |
Stand Minutes | min |
quantity |
| Activity | appleStandHour |
Stand Hours | min |
category |
| Activity | distanceCycling |
Cycling Distance | km |
quantity |
| Activity | distanceSwimming |
Swimming Distance | m |
quantity |
| Activity | swimmingStrokeCount |
Swimming Strokes | count |
quantity |
| Activity | physicalEffort |
Physical Effort | kcal/hr*kg |
quantity |
| Running | runningSpeed |
Running Speed | km/hr |
quantity |
| Running | runningPower |
Running Power | W |
quantity |
| Running | runningStrideLength |
Running Stride Length | m |
quantity |
| Running | runningGroundContactTime |
Ground Contact Time | ms |
quantity |
| Running | runningVerticalOscillation |
Vertical Oscillation | cm |
quantity |
| Workouts | workout |
Workouts | min |
workout |
| Workouts | workoutEffortScore |
Workout Effort | appleEffortScore |
quantity |
| Workouts | estimatedWorkoutEffortScore |
Estimated Workout Effort | appleEffortScore |
quantity |
| Workouts | cyclingSpeed |
Cycling Speed | km/hr |
quantity |
| Workouts | cyclingPower |
Cycling Power | W |
quantity |
| Workouts | cyclingCadence |
Cycling Cadence | count/min |
quantity |
| Workouts | cyclingFunctionalThresholdPower |
Cycling FTP | W |
quantity |
| Workouts | distanceRowing |
Rowing Distance | km |
quantity |
| Workouts | rowingSpeed |
Rowing Speed | km/hr |
quantity |
| Workouts | distancePaddleSports |
Paddle Sports Distance | km |
quantity |
| Workouts | paddleSportsSpeed |
Paddle Sports Speed | km/hr |
quantity |
| Workouts | distanceSkatingSports |
Skating Distance | km |
quantity |
| Workouts | distanceCrossCountrySkiing |
Cross-Country Skiing Distance | km |
quantity |
| Workouts | crossCountrySkiingSpeed |
Cross-Country Skiing Speed | km/hr |
quantity |
| Workouts | underwaterDepth |
Underwater Depth | m |
quantity |
| Workouts | waterTemperature |
Water Temperature | degC |
quantity |
| Mobility | walkingSpeed |
Walking Speed | km/hr |
quantity |
| Mobility | walkingStepLength |
Walking Step Length | cm |
quantity |
| Mobility | walkingAsymmetryPercentage |
Walking Asymmetry | % |
quantity |
| Mobility | walkingDoubleSupportPercentage |
Double Support Time | % |
quantity |
| Mobility | appleWalkingSteadiness |
Walking Steadiness | % |
quantity |
| Mobility | stairAscentSpeed |
Stair Speed: Up | m/s |
quantity |
| Mobility | stairDescentSpeed |
Stair Speed: Down | m/s |
quantity |
| Mobility | sixMinuteWalkTestDistance |
Six-Minute Walk | m |
quantity |
| Heart | heartRate |
Heart Rate | count/min |
quantity |
| Heart | restingHeartRate |
Resting Heart Rate | count/min |
quantity |
| Heart | walkingHeartRateAverage |
Walking Heart Rate Average | count/min |
quantity |
| Heart | heartRateVariabilitySDNN |
Heart Rate Variability | ms |
quantity |
| Heart | bloodPressureSystolic |
Blood Pressure (Systolic) | mmHg |
quantity |
| Heart | bloodPressureDiastolic |
Blood Pressure (Diastolic) | mmHg |
quantity |
| Heart | vo2Max |
Cardio Fitness (VO₂ max) | ml/kg*min |
quantity |
| Heart | heartRateRecoveryOneMinute |
Heart Rate Recovery | count/min |
quantity |
| Body Measurements | bodyMass |
Weight | kg |
quantity |
| Body Measurements | height |
Height | cm |
quantity |
| Body Measurements | bodyMassIndex |
Body Mass Index | count |
quantity |
| Body Measurements | bodyFatPercentage |
Body Fat Percentage | % |
quantity |
| Respiratory | respiratoryRate |
Respiratory Rate | count/min |
quantity |
| Respiratory | oxygenSaturation |
Blood Oxygen | % |
quantity |
| Sleep | sleepAnalysis |
Sleep Stages | min |
category |
| Sleep | appleSleepingWristTemperature |
Wrist Temperature | degC |
quantity |
| Sleep | appleSleepingBreathingDisturbances |
Breathing Disturbances | count/hr |
quantity |
| Sleep | sleepApneaEvent |
Sleep Apnea Events | min |
category |
| Nutrition | dietaryEnergyConsumed |
Dietary Energy | kcal |
quantity |
| Nutrition | dietaryProtein |
Protein | g |
quantity |
| Nutrition | dietaryCarbohydrates |
Carbohydrates | g |
quantity |
| Nutrition | dietaryFatTotal |
Total Fat | g |
quantity |
| Nutrition | dietarySugar |
Sugar | g |
quantity |
| Nutrition | dietaryFiber |
Fibre | g |
quantity |
| Nutrition | dietarySodium |
Sodium | mg |
quantity |
| Nutrition | dietaryCaffeine |
Caffeine | mg |
quantity |
| Nutrition | numberOfAlcoholicBeverages |
Alcoholic Drinks | count |
quantity |
| Nutrition | dietaryWater |
Water | mL |
quantity |
| Hearing | environmentalAudioExposure |
Environmental Sound Levels | dBASPL |
quantity |
| Hearing | headphoneAudioExposure |
Headphone Audio Levels | dBASPL |
quantity |
| Cycle Tracking | menstrualFlow |
Menstrual Flow | min |
category |
| Cycle Tracking | intermenstrualBleeding |
Spotting | min |
category |
| Cycle Tracking | ovulationTestResult |
Ovulation Test | min |
category |
| Cycle Tracking | cervicalMucusQuality |
Cervical Mucus Quality | min |
category |