<!--
{
  "availability" : [
    "iOS: 12.0.0 -",
    "iPadOS: 12.0.0 -",
    "macCatalyst: 13.1.0 -",
    "macOS: -",
    "visionOS: 1.0.0 -",
    "watchOS: 5.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "HealthKit",
  "identifier" : "/documentation/HealthKit/HKWorkoutBuilder",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "HealthKit"
    ],
    "preciseIdentifier" : "c:objc(cs)HKWorkoutBuilder"
  },
  "title" : "HKWorkoutBuilder"
}
-->

# HKWorkoutBuilder

A builder object that incrementally constructs a workout.

```
class HKWorkoutBuilder
```

## Overview

Incrementally collect samples and events associated with a workout. When the workout ends, call [`finishWorkout(completion:)`](/documentation/HealthKit/HKWorkoutBuilder/finishWorkout(completion:)) to create an [`HKWorkout`](/documentation/HealthKit/HKWorkout) sample and save it to the HealthKit store.

For watchOS, use an [`HKWorkoutSession`](/documentation/HealthKit/HKWorkoutSession) and an [`HKLiveWorkoutBuilder`](/documentation/HealthKit/HKLiveWorkoutBuilder) instead.

## Topics

### Creating the builder

[`init(healthStore:configuration:device:)`](/documentation/HealthKit/HKWorkoutBuilder/init(healthStore:configuration:device:))

Returns a new workout builder object that is not connected to a workout session or other data source.

[`device`](/documentation/HealthKit/HKWorkoutBuilder/device)

The device associated with the workout.

[`workoutConfiguration`](/documentation/HealthKit/HKWorkoutBuilder/workoutConfiguration)

The configuration information for the workout.

### Starting the workout

[`beginCollection(withStart:completion:)`](/documentation/HealthKit/HKWorkoutBuilder/beginCollection(withStart:completion:))

Sets the workout’s start date and begins building the workout.

[`startDate`](/documentation/HealthKit/HKWorkoutBuilder/startDate)

The workout’s start date and time.

[`elapsedTime(at:)`](/documentation/HealthKit/HKWorkoutBuilder/elapsedTime(at:))

Calculates the duration of the workout at the specified time.

### Associating samples with the workout

[`add(_:completion:)`](/documentation/HealthKit/HKWorkoutBuilder/add(_:completion:))

Adds a sample to be associated with the workout.

[`seriesBuilder(for:)`](/documentation/HealthKit/HKWorkoutBuilder/seriesBuilder(for:))

Returns the series builder for the specified type, creating a new builder, if necessary.

[`statistics(for:)`](/documentation/HealthKit/HKWorkoutBuilder/statistics(for:))

Returns the statistics calculated for matching samples added to the workout.

### Adding metadata to the workout

[`addMetadata(_:completion:)`](/documentation/HealthKit/HKWorkoutBuilder/addMetadata(_:completion:))

Adds metadata to be saved with the workout.

[`metadata`](/documentation/HealthKit/HKWorkoutBuilder/metadata)

The metadata the builder saves with the workout.

### Adding events to the workout

[`addWorkoutEvents(_:completion:)`](/documentation/HealthKit/HKWorkoutBuilder/addWorkoutEvents(_:completion:))

Adds a workout event to the builder.

[`workoutEvents`](/documentation/HealthKit/HKWorkoutBuilder/workoutEvents)

The list of events added to the workout.

### Managing workout activities

[`addWorkoutActivity(_:completion:)`](/documentation/HealthKit/HKWorkoutBuilder/addWorkoutActivity(_:completion:))

Adds a workout activity to the workout builder.

[`updateActivity(uuid:adding:completion:)`](/documentation/HealthKit/HKWorkoutBuilder/updateActivity(uuid:adding:completion:))

Adds metadata to a workout activity that you’ve already added to the workout builder.

[`updateActivity(uuid:end:completion:)`](/documentation/HealthKit/HKWorkoutBuilder/updateActivity(uuid:end:completion:))

Sets the end date for a workout activity that you’ve already added to the workout builder.

[`workoutActivities`](/documentation/HealthKit/HKWorkoutBuilder/workoutActivities)

### Ending the workout

[`endCollection(withEnd:completion:)`](/documentation/HealthKit/HKWorkoutBuilder/endCollection(withEnd:completion:))

Stops the collection of data, sets the workout’s end date, and deactivates the workout builder.

[`endDate`](/documentation/HealthKit/HKWorkoutBuilder/endDate)

The workout’s end date and time.

[`finishWorkout(completion:)`](/documentation/HealthKit/HKWorkoutBuilder/finishWorkout(completion:))

Creates the workout, using the samples and events added to the builder, and saves it to the HealthKit store.

[`discardWorkout()`](/documentation/HealthKit/HKWorkoutBuilder/discardWorkout())

Stops the collection of data and discards the current results without saving the workout.

### Accessing workout statistics

[`allStatistics`](/documentation/HealthKit/HKWorkoutBuilder/allStatistics)

A dictionary that contains all the statistics for the workout builder.

### Configuring zone data

[`setCustomZoneConfiguration(_:for:)`](/documentation/HealthKit/HKWorkoutBuilder/setCustomZoneConfiguration(_:for:))

Overrides the preferred zone configuration with a custom zone for the current workout.

[`zoneConfiguration(for:)`](/documentation/HealthKit/HKWorkoutBuilder/zoneConfiguration(for:))

Returns the zone configuration for the specified quantity type.

[`zoneGroup(for:)`](/documentation/HealthKit/HKWorkoutBuilder/zoneGroup(for:))

Returns the current zone group for the specified quantity type.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)