Help Center HealthyApps
English
Help Center
Main website ↗

Search help topics

Workouts - JSON Export Format

Documentation for workouts structure in JSON exports

Last updated: October 31, 2026

On this page
Export Versions
Workouts Version 2 Workouts Version 2 Basic StructureRequired FieldsOptional FieldsWorkout Metrics Time Grouping
Workouts Version 1 (Legacy) Workouts Version 1 (Legacy) Version 1 Structure
Related Documentation

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 workout
  • name (String): Workout type name (e.g., "Running", "Cycling", "Swimming")
  • start (Date): Workout start time in format yyyy-MM-dd HH:mm:ss Z
  • end (Date): Workout end time in format yyyy-MM-dd HH:mm:ss Z
  • duration (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 workout
  • totalEnergy (Object): Total calories (active + resting) burned
  • intensity (Object): Metabolic equivalent of task (MET) value

Distance and Speed

{
  "distance": {
    "qty": 3.5,
    "units": "mi"
  }
}
  • distance (Object): Total distance covered
  • speed (Object): Average speed calculated from distance and duration
  • avgSpeed (Object): Average speed throughout the workout
  • maxSpeed (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 gained
  • elevationDown (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 workout
  • humidity (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 lap
  • strokeStyle (String): One of:
    • "Backstroke"
    • "Breaststroke"
    • "Butterfly"
    • "Freestyle"
    • "Mixed"
    • "Kickboard"
    • "Unknown"
  • swolfScore (Number): Swimming efficiency score
  • salinity (String): "Fresh Water" or "Salt Water"
  • totalSwimmingStrokeCount (Object): Total number of strokes
  • swimCadence (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 time
  • stepCadence (Object): Steps per minute
  • flightsClimbed (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 workout
  • maxHeartRate (Object): Maximum heart rate during the workout
  • avgHeartRate (Object): Average heart rate during the workout
  • heartRateData (Array): Detailed measurements from the workout, ending when the workout ends
  • heartRateRecovery (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 measurement
  • qty (Number): Quantity value
  • units (String): Unit of measurement
  • source (String, optional): Data source device or app

HeartRateData Structure:

  • date (Date): Timestamp of the measurement
  • Min (Number): Minimum heart rate
  • Avg (Number): Average heart rate
  • Max (Number): Maximum heart rate
  • units (String): Unit (count/min with 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 coordinate
  • longitude (Number): GPS longitude coordinate
  • altitude (Number): Elevation in meters
  • course (Number): Direction of travel in degrees (0-360)
  • courseAccuracy (Number): Accuracy of course measurement in degrees
  • horizontalAccuracy (Number): Horizontal position accuracy in meters
  • verticalAccuracy (Number): Vertical position accuracy in meters
  • timestamp (Date): Time when location was recorded
  • speed (Number): Speed in meters per second
  • speedAccuracy (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"
    }
  ]
}