Which HealthConnectClient method should I use to read health data?

It depends on the shape of the answer you want. For the records themselves, use readRecords with a ReadRecordsRequest and follow its pageToken. For a total, average, minimum or maximum over one window, use aggregate with an AggregateRequest; Google's read guide says to use it instead of readRecords for cumulative types such as steps, to avoid double counting from multiple sources. For one value per bucket, use aggregateGroupByDuration for fixed lengths of time or aggregateGroupByPeriod for calendar days, weeks or months. To read only what changed since your last sync, including deletions, use getChangesToken and getChanges.

Are Health Connect writes and deletes transactional?

Per call, yes. Google's HealthConnectClient reference says insertion of multiple records is executed in a transaction, so if one fails none is inserted; updateRecords is described the same way, and both deleteRecords forms say that if one deletion fails, none is deleted. The transaction covers a single call, so if you split a large batch into several calls, an earlier call that succeeded stays committed when a later one fails.

Which exceptions can HealthConnectClient methods throw?

Google's reference lists RemoteException for IPC transport failures, SecurityException for requests with unpermitted access and IOException for disk I/O issues on the read, aggregate, insert, update and delete methods. Google's read guide adds IllegalStateException, thrown when the Health Connect service is not available or the request is not a valid construction, such as a period-bucketed aggregate given an Instant time range. Its paging sample also catches IllegalStateException as a quota error and backs off.

Health Connect Jetpack API, Method by Method

Health Connect API

Health Connect’s Jetpack client, HealthConnectClient, does its work through a small set of suspend functions: readRecords for raw records, aggregate and its two bucketed variants for totals, getChangesToken and getChanges for incremental sync, insertRecords, updateRecords and deleteRecords for writes, and PermissionController for access. Each page here covers one method or class: what Google’s reference documents, a short Kotlin sketch built from documented signatures, and the traps that return a wrong answer without an error. Every claim comes from Google’s own Android developer documentation, and where Google is silent the page says so.

These pages explain how each call behaves. Setting Health Connect up (the dependency, manifest permissions, checking the SDK is available and the first permission request) is covered in the Google Health Connect integration guide. Specific failures, such as a read that returns nothing or a SecurityException, have their own troubleshooting pages. The record types themselves, with their fields and permission strings, are listed in the Health Connect record reference.

Reading records

Raw records one page at a time, and the permissions that decide how far back and when your app may read.

Totals and buckets

Let Health Connect compute the sum, average or extreme, once for a window or once per minute, hour, day or month.

Keeping up with changes

What was inserted, updated or deleted since your last sync, using a changes token.

getChanges and getChangesToken: incremental sync from Health ConnectHow getChangesToken and getChanges work: ChangesTokenRequest, the hasMore loop, nextChangesToken, UpsertionChange, DeletionChange and one token per type.UpdatedVerified October 4, 2026

Writing and deleting

Upserts keyed on your own ids, the metadata every write must carry, and removing what your app wrote.

Permissions and availability

Requesting, checking and revoking access, the permission screens Google expects, and checking a feature exists before you call it.

Exercise data

GPS routes and the consent they need, and planned sessions for training plans.

Coming from HealthKit

Which Health Connect call does the job of each HealthKit query.

HealthKit to Health Connect: the API equivalents, call by callMap HealthKit calls to Health Connect: HKSampleQuery to readRecords, HKStatisticsQuery to aggregate, anchors to getChanges, and what has no equivalent.UpdatedVerified October 4, 2026

Frequently asked questions

Which HealthConnectClient method should I use to read health data?: It depends on the shape of the answer you want. For the records themselves, use readRecords with a ReadRecordsRequest and follow its pageToken. For a total, average, minimum or maximum over one window, use aggregate with an AggregateRequest; Google's read guide says to use it instead of readRecords for cumulative types such as steps, to avoid double counting from multiple sources. For one value per bucket, use aggregateGroupByDuration for fixed lengths of time or aggregateGroupByPeriod for calendar days, weeks or months. To read only what changed since your last sync, including deletions, use getChangesToken and getChanges.
Are Health Connect writes and deletes transactional?: Per call, yes. Google's HealthConnectClient reference says insertion of multiple records is executed in a transaction, so if one fails none is inserted; updateRecords is described the same way, and both deleteRecords forms say that if one deletion fails, none is deleted. The transaction covers a single call, so if you split a large batch into several calls, an earlier call that succeeded stays committed when a later one fails.
Which exceptions can HealthConnectClient methods throw?: Google's reference lists RemoteException for IPC transport failures, SecurityException for requests with unpermitted access and IOException for disk I/O issues on the read, aggregate, insert, update and delete methods. Google's read guide adds IllegalStateException, thrown when the Health Connect service is not available or the request is not a valid construction, such as a period-bucketed aggregate given an Instant time range. Its paging sample also catches IllegalStateException as a quota error and backs off.

All 58 questions in Health Connect API, answered

Independent comparison, last reviewed October 4, 2026. Pricing, rate limits, and feature availability change often — confirm current details in each provider’s official documentation before you commit. Product and company names are trademarks of their respective owners; AIFitnessAPI is not affiliated with, endorsed by, or sponsored by any product listed here.