Fitness & activity tracking
Recording a workout with laps and a GPS route, then reading the history back.
An exercise session is the richest record type in the SDK: it carries a type, a title, notes, lap and segment events, and an optional route.
Record a run with laps and a route
Future<void> recordRunWithRoute() async {
// 1. Route access requires the session permission as well.
final results = await connector.requestPermissions([
HealthDataType.exerciseSession.writePermission,
HealthDataType.exerciseSession.writeExerciseRoutePermission,
]);
if (results.any((r) => r.status == PermissionStatus.denied)) return;
final startTime = DateTime.now();
final endTime = startTime.add(const Duration(minutes: 35));
// 2. Laps — 400m track intervals.
final laps = [
ExerciseSessionLapEvent(
startTime: startTime,
endTime: startTime.add(const Duration(minutes: 2, seconds: 5)),
distance: Length.meters(400),
),
ExerciseSessionLapEvent(
startTime: startTime.add(const Duration(minutes: 2, seconds: 5)),
endTime: startTime.add(const Duration(minutes: 4, seconds: 8)),
distance: Length.meters(400),
),
ExerciseSessionLapEvent(
startTime: startTime.add(const Duration(minutes: 4, seconds: 8)),
endTime: startTime.add(const Duration(minutes: 6, seconds: 15)),
distance: Length.meters(400),
),
// ... more laps
];
// 3. The GPS track. Recording horizontalAccuracy lets you filter
// noisy points later instead of drawing a track through buildings.
final route = ExerciseRoute([
ExerciseRouteLocation(
time: startTime,
latitude: 37.7749,
longitude: -122.4194,
altitude: Length.meters(15),
horizontalAccuracy: Length.meters(5),
),
ExerciseRouteLocation(
time: startTime.add(const Duration(seconds: 30)),
latitude: 37.7752,
longitude: -122.4190,
altitude: Length.meters(16),
horizontalAccuracy: Length.meters(4),
),
ExerciseRouteLocation(
time: startTime.add(const Duration(minutes: 1)),
latitude: 37.7755,
longitude: -122.4185,
altitude: Length.meters(17),
horizontalAccuracy: Length.meters(3),
),
// ... more GPS points recorded during the run
]);
// 4. One record carries the session, its events, and its route.
final runSession = ExerciseSessionRecord(
startTime: startTime,
endTime: endTime,
exerciseType: ExerciseType.running,
title: 'Morning Run',
notes: 'Easy pace around the park. Good weather.',
events: laps,
exerciseRoute: route,
metadata: Metadata.automaticallyRecorded(
device: Device.fromType(DeviceType.watch),
),
);
// 5. A single write.
await connector.writeRecord(runSession);
}Check exercise type availability
ExerciseType covers 96 activities, and they do not all exist on both stores — ExerciseType.runningTreadmill is Health Connect-only, for example. Search the exercise type reference before hard-coding one.
Read exercise history
Routes do not come back with the session query. Load them separately, and only for the sessions you will actually draw:
Future<void> getExerciseHistory() async {
// 1. Read access, including routes.
await connector.requestPermissions([
HealthDataType.exerciseSession.readPermission,
HealthDataType.exerciseSession.readExerciseRoutePermission,
]);
// 2. Read the sessions.
final now = DateTime.now();
final monthAgo = now.subtract(const Duration(days: 30));
final response = await connector.readRecords(
HealthDataType.exerciseSession.readInTimeRange(
startTime: monthAgo,
endTime: now,
),
);
print('Exercise History (Past 30 Days):');
print(' Total workouts: ${response.records.length}');
for (final session in response.records) {
final duration = session.endTime.difference(session.startTime);
print('\n ${session.exerciseType.name.toUpperCase()}');
print(' Title: ${session.title ?? "Untitled"}');
print(' Duration: ${duration.inMinutes} min');
print(' Laps: ${session.lapEvents.length}');
print(' Segments: ${session.segmentEvents.length}');
}
}Everything in that list comes from the session records themselves — no route call needed. Load a route only when the user opens one workout:
Future<void> showWorkoutMap(HealthRecordId sessionId) async {
final route = await connector.readExerciseRoute(sessionId);
if (route == null || route.isEmpty) return showNoRouteState();
drawOnMap(route.locations);
}Never loop readExerciseRoute() over a list
Each call is a separate round trip carrying a full GPS track. Fetching a route per session to render a list turns one query into dozens, moves a lot of location data you will not draw, and on Android pushes you toward rateLimitExceeded.
Read active energy for a workout
For a saved session from the history query, use the workout energy builder:
final Energy energy = await connector.aggregate(
HealthDataType.exerciseSession.aggregateActiveEnergyBurnedFor(
exerciseSession: session,
),
);
print('Active energy: ${energy.inKilocalories} kcal');On Android, also request HealthDataType.activeEnergyBurned.readPermission. Health Connect sums energy from the workout's source during its time range, so other activity in that interval can be included. HealthKit reads the energy associated with the saved workout and requires workout read access. See workout active energy for missing-record behavior and iOS version differences.
Strength training and extended segment fields
Segments describe what happened inside a session — sets, reps, load, and perceived effort. Check the runtime requirement before including fields that need Health Connect SDK Extension 21:
final support = connector.getSupportStatusFor(
ExerciseSessionSegmentEvent.extendedFieldsRequirements,
);
final supportsExtendedFields = support.isSupported;
final startTime = DateTime.now();
final endTime = startTime.add(const Duration(minutes: 1));
final segment = ExerciseSessionSegmentEvent(
startTime: startTime,
endTime: endTime,
segmentType: ExerciseSegmentType.benchPress,
repetitions: 10,
weight: supportsExtendedFields ? Mass.kilograms(80) : null,
setIndex: supportsExtendedFields ? 0 : null,
rateOfPerceivedExertion: supportsExtendedFields ? 7.5 : null,
);
final exerciseSession = ExerciseSessionRecord(
startTime: startTime,
endTime: endTime,
exerciseType: ExerciseType.strengthTraining,
events: [segment],
metadata: Metadata.automaticallyRecorded(
device: Device.fromType(DeviceType.watch),
),
);
try {
await connector.writeRecord(exerciseSession);
} on UnsupportedOperationException catch (e) {
// The device's Health Connect module predates Extension 21,
// or this is iOS. Omit the fields or tell the user.
print('Extended segment fields are not supported: $e');
}Extended fields require a runtime device check
The same binary succeeds on one Android 14 device and throws on another, depending on whether that device received the relevant Health Connect Mainline update. Always check extendedFieldsRequirements and retain an unsupported operation fallback. Full behavior table.