Workouts - JSON Export Format
Documentation for workouts structure in JSON exports
Last updated: October 31, 2026
On this page
JSON exports store workouts in the workouts array.
Export Versions
Health Auto Export supports two workout export versions:
- Version 2 (Recommended): Enhanced format with more detailed metadata and structured data
- Version 1 (Legacy): Older format maintained for compatibility with existing workflows
Workouts Version 2
Version 2 includes the following required fields and optional data. Examples use Localize Units off; enabling it can change unit labels in metric series.
Basic Structure
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Running",
"start": "2024-02-06 07:00:00 -0800",
"end": "2024-02-06 07:30:00 -0800",
"duration": 1800
}
Required Fields
id(String): Unique identifier for the workoutname(String): Workout type name (e.g., "Running", "Cycling", "Swimming")start(Date): Workout start time in formatyyyy-MM-dd HH:mm:ss Zend(Date): Workout end time in formatyyyy-MM-dd HH:mm:ss Zduration(Number): Workout duration in seconds
Optional Fields
Optional fields depend on available data and your export selections:
Recording Source
{
"source": {
"name": "Workout App",
"identifier": "com.example.workouts"
}
}
source(Object): The app or device that recorded the workout, with its name and app identifier. Individual metric readings have separate source strings and may come from another app or device.
Location Information
{
"location": "Outdoor",
"isIndoor": false
}
location(String): One of"Indoor","Outdoor","Pool","Open Water"isIndoor(Boolean): Whether the workout was performed indoors
Energy and Intensity
{
"activeEnergyBurned": {
"qty": 350,
"units": "kcal"
},
"totalEnergy": {
"qty": 450,
"units": "kcal"
},
"intensity": {
"qty": 8.5,
"units": "kcal/hr\u00b7kg"
}
}
activeEnergyBurned(Object): Active calories burned during the workouttotalEnergy(Object): Total calories (active + resting) burnedintensity(Object): Metabolic equivalent of task (MET) value
Distance and Speed
{
"distance": {
"qty": 3.5,
"units": "mi"
}
}
distance(Object): Total distance coveredspeed(Object): Average speed calculated from distance and durationavgSpeed(Object): Average speed throughout the workoutmaxSpeed(Object): Maximum speed reached
Each object includes qty and units.
Elevation
{
"elevationUp": {
"qty": 500,
"units": "ft"
},
"elevationDown": {
"qty": 450,
"units": "ft"
}
}
elevationUp(Object): Total elevation gainedelevationDown(Object): Total elevation lost
Units: "ft" (feet) or "m" (meters)
Environmental Data
{
"temperature": {
"qty": 72,
"units": "degF"
},
"humidity": {
"qty": 65,
"units": "%"
}
}
temperature(Object): Ambient temperature during workouthumidity(Object): Relative humidity percentage
Temperature Units: "degF" (Fahrenheit) or "degC" (Celsius)
Swimming-Specific Fields
{
"lapLength": {
"qty": 0.025,
"units": "mi"
},
"strokeStyle": "Freestyle",
"swolfScore": 45,
"salinity": "Fresh Water",
"totalSwimmingStrokeCount": {
"qty": 1200,
"units": "count"
},
"swimCadence": {
"qty": 30,
"units": "count/min"
}
}
lapLength(Object): Length of each lapstrokeStyle(String): One of:"Backstroke""Breaststroke""Butterfly""Freestyle""Mixed""Kickboard""Unknown"
swolfScore(Number): Swimming efficiency scoresalinity(String):"Fresh Water"or"Salt Water"totalSwimmingStrokeCount(Object): Total number of strokesswimCadence(Object): Strokes per minute
Step and Cadence Data
{
"stepCount": [
{
"date": "2024-02-06 07:00:00 -0800",
"qty": 5000,
"units": "count",
"source": "Apple Watch"
}
],
"stepCadence": {
"qty": 180,
"units": "count/min"
},
"flightsClimbed": {
"qty": 10,
"units": "count"
}
}
stepCount(Array): Array of step count measurements over timestepCadence(Object): Steps per minuteflightsClimbed(Object): Number of flights of stairs climbed
Heart Rate Data
{
"heartRate": {
"min": {
"qty": 120,
"units": "count/min"
},
"avg": {
"qty": 150,
"units": "count/min"
},
"max": {
"qty": 175,
"units": "count/min"
}
},
"maxHeartRate": {
"qty": 175,
"units": "count/min"
},
"avgHeartRate": {
"qty": 150,
"units": "count/min"
},
"heartRateData": [
{
"date": "2024-02-06 07:00:00 -0800",
"Min": 120,
"Avg": 150,
"Max": 175,
"units": "count/min",
"source": "Apple Watch"
}
],
"heartRateRecovery": [
{
"date": "2024-02-06 07:30:00 -0800",
"Min": 140,
"Avg": 145,
"Max": 150,
"units": "count/min",
"source": "Apple Watch"
}
]
}
heartRate(Object): Summary with min, avg, and max heart rate during the workoutmaxHeartRate(Object): Maximum heart rate during the workoutavgHeartRate(Object): Average heart rate during the workoutheartRateData(Array): Detailed measurements from the workout, ending when the workout endsheartRateRecovery(Array): Separate measurements from the two minutes immediately after the workout ends
Summary heart rates use recorded workout values when available, falling back to the workout’s heart-rate readings. The exported readings include measurements taken during pauses, so their peaks and averages may differ from the summary.
Time-Series Data Arrays
Many metrics can be included as time-series arrays when "Include Workout Metrics" is enabled:
{
"activeEnergy": [
{
"date": "2024-02-06 07:00:00 -0800",
"qty": 50,
"units": "kcal",
"source": "Apple Watch"
}
],
"basalEnergy": [
{
"date": "2024-02-06 07:00:00 -0800",
"qty": 20,
"units": "kcal",
"source": "Apple Watch"
}
],
"cyclingCadence": [
{
"date": "2024-02-06 07:00:00 -0800",
"qty": 90,
"units": "count/min",
"source": "Apple Watch"
}
],
"cyclingDistance": [
{
"date": "2024-02-06 07:00:00 -0800",
"qty": 0.5,
"units": "mi",
"source": "Apple Watch"
}
],
"cyclingPower": [
{
"date": "2024-02-06 07:00:00 -0800",
"qty": 200,
"units": "W",
"source": "Power Meter"
}
],
"cyclingSpeed": [
{
"date": "2024-02-06 07:00:00 -0800",
"qty": 18,
"units": "mi/hr",
"source": "Apple Watch"
}
],
"swimDistance": [
{
"date": "2024-02-06 07:00:00 -0800",
"qty": 25,
"units": "yd",
"source": "Apple Watch"
}
],
"swimStroke": [
{
"date": "2024-02-06 07:00:00 -0800",
"qty": 20,
"units": "count",
"source": "Apple Watch"
}
],
"walkingAndRunningDistance": [
{
"date": "2024-02-06 07:00:00 -0800",
"qty": 0.25,
"units": "mi",
"source": "Apple Watch"
}
]
}
QuantityData Structure:
date(Date): Timestamp of the measurementqty(Number): Quantity valueunits(String): Unit of measurementsource(String, optional): Data source device or app
HeartRateData Structure:
date(Date): Timestamp of the measurementMin(Number): Minimum heart rateAvg(Number): Average heart rateMax(Number): Maximum heart rateunits(String): Unit (count/minwith Localize Units off)source(String, optional): Data source device or app
Route Data
When "Include Route Data" is enabled and the workout has GPS data:
{
"route": [
{
"latitude": 37.7749,
"longitude": -122.4194,
"altitude": 50.5,
"course": 45.0,
"courseAccuracy": 5.0,
"horizontalAccuracy": 10.0,
"verticalAccuracy": 15.0,
"timestamp": "2024-02-06 07:00:00 -0800",
"speed": 7.0,
"speedAccuracy": 0.5
}
]
}
Location Fields:
latitude(Number): GPS latitude coordinatelongitude(Number): GPS longitude coordinatealtitude(Number): Elevation in meterscourse(Number): Direction of travel in degrees (0-360)courseAccuracy(Number): Accuracy of course measurement in degreeshorizontalAccuracy(Number): Horizontal position accuracy in metersverticalAccuracy(Number): Vertical position accuracy in meterstimestamp(Date): Time when location was recordedspeed(Number): Speed in meters per secondspeedAccuracy(Number): Accuracy of speed measurement in m/s
Metadata
{
"metadata": {
"customField": {
"label": "value",
"quantity": 123
},
"anotherField": [
1,
2,
3
]
}
}
metadata(Object): Additional custom metadata associated with the workout
Events, Activities, and Splits
Version 2 JSON and Markdown exports may include events, segments, laps, and activities recorded by the workout app. These remain available when Include Workout Metrics is off. CSV and GPX do not include these records.
With Include Workout Metrics on and the relevant metrics selected, intervals may also include distance, active energy, heart-rate summaries, and active-time pace or speed. Values distinguish recorded measurements from estimates; unavailable values are omitted.
With distance selected, splits may include estimated kilometre and mile splits. They can differ from the recording app’s splits, and the final split is marked partial when shorter than the target distance. Missing distance readings or unsupported workout types can prevent split calculation.
Workout Effort Scores
Version 2 JSON and Markdown exports can include selected Workout Effort Score (effortScore) and Estimated Workout Effort Score (estimatedEffortScore) values. Each is an object with qty and units: "appleEffortScore".
Scores require iOS 18 or later and access to the corresponding data in Apple Health. Whole-workout and activity scores are separate. They are independent of Time Grouping and Include Workout Metrics; CSV does not include them.
In Browse → Workouts, open the list’s export sheet or a workout’s Version 2 export settings, then use Select Export Fields to choose effort scores before exporting.
Workout Metrics Time Grouping
When using Export Version 2 and "Include Workout Metrics" is enabled, you can control the granularity of time-series data:
- Minutes: Groups workout metrics on clock minutes. The first and last minute can include a few seconds just before the workout starts or just after it ends.
- Seconds: Groups workout metrics on clock seconds, with each timestamp marking the start of its second. The first and last second can include the fraction of a second just outside the workout. Files are larger than minute grouping.
Active and resting energy use the same combined totals as other workout metrics in each time group. Readings from more than one device or app are included together.
Workouts Version 1 (Legacy)
Version 1 uses a simpler structure. For new exports, Version 2 is recommended.
Version 1 Structure
{
"name": "Running",
"start": "2024-02-06 07:00:00 -0800",
"end": "2024-02-06 07:30:00 -0800",
"totalEnergy": {
"qty": 450,
"units": "kcal"
},
"activeEnergy": {
"qty": 350,
"units": "kcal"
},
"distance": {
"qty": 3.5,
"units": "mi"
},
"heartRateData": [
{
"date": "2024-02-06 07:00:00 -0800",
"qty": 150,
"units": "bpm"
}
],
"route": [
{
"lat": 37.7749,
"lon": -122.4194,
"altitude": 50.5,
"timestamp": "2024-02-06 07:00:00 -0800"
}
]
}