Every question the Health Connect API pages answer
The 15 health connect api pages answer 58 named questions between them. Every one is listed below, and every link lands on the paragraph that answers it rather than the top of the page.
readRecords and ReadRecordsRequest: paging with pageSize and pageToken
- What is the default pageSize of a Health Connect ReadRecordsRequest?1000. Google's ReadRecordsRequest reference shows pageSize defaulting to 1000, and the read guide says that if the number of records…
- Why does ReadRecordsResponse.pageToken come back as an empty string instead of null?Because some versions return it that way. Google's read guide notes that depending on the system or Health Connect APK version, such as on…
- Should I sum StepsRecord values from readRecords to get a daily step total?No. Google's read guide says that for cumulative types like StepsRecord you should use aggregate() instead of readRecords() to avoid double…
- Does TimeRangeFilter.between include a record that starts exactly at the end time?No. Google's TimeRangeFilter reference describes between as inclusive-exclusive: a record at the start time is included and one at the end…
aggregate() and AggregateRequest: totals, averages and deduplicated sources
- Does Health Connect's aggregate API remove duplicate steps written by different apps?For Activity and Sleep data, yes. Google's aggregate guide says users can set a priority order for their Activity and Sleep apps, and that…
- Why does an AggregationResult return null for a metric I asked for?Because no records contributed to it. Google's AggregationResult reference says that if there are no relevant records contributing to the…
- Can one Health Connect AggregateRequest include metrics from different record types?Yes. The metrics parameter is a set of AggregateMetric values, and the example on Google's AggregationResult reference requests a steps…
- How can I tell which apps contributed to a Health Connect aggregate value?Read the dataOrigins property of the AggregationResult. Google's reference describes it as the set of DataOrigin values that contributed to…
aggregateGroupByDuration vs aggregateGroupByPeriod: fixed buckets or calendar buckets
- Should I use aggregateGroupByDuration or aggregateGroupByPeriod for daily step totals?aggregateGroupByPeriod with Period.ofDays(1). Google's reference describes a Period slice as a variable-length interval such as a day,…
- Why does aggregateGroupByPeriod throw an IllegalStateException?The most likely cause is an Instant time range. Google's aggregate guide says that when running bucket aggregates per period, the start and…
- Why are some days missing from my aggregateGroupByPeriod results?Because the result list is sparse. Google's aggregate guide says a bucket is not included in the list if it does not contain any data, and…
- What is the zoneOffset on an AggregationResultGroupedByDuration?It is the offset of the records inside that slice. Google's reference describes it as the zone offset of the underlying record within the…
getChanges and getChangesToken: incremental sync from Health Connect
- What does hasMore mean in a Health Connect ChangesResponse?It means the response did not include every pending change. Google's getChanges reference says a response may not provide all the changes…
- Why does a Health Connect DeletionChange not include the record type?For privacy. Google's DeletionChange reference says only the unique identifiers of the deletion are returned, exposed as recordId, which is…
- Should one Health Connect changes token cover several record types?Usually not. Google's sync guide recommends getting separate tokens per data type instead of in bulk, to avoid an exception if one of the…
- Can getChanges hand my app back the records it wrote itself?Google's sync guide treats that as expected. Its steps say that for an UpsertionChange you should only take changes that did not come from…
insertRecords and clientRecordId: how Health Connect upserts
- What happens when I insert a Health Connect record with a clientRecordId that already exists?It becomes an update or is ignored, never a duplicate. Google's Metadata reference says there is guaranteed a single entry for any type of…
- Does Health Connect increment clientRecordVersion automatically?No. Google's write guide says upserts don't automatically increment the version whenever there are changes, so that data is not overwritten…
- When should I use updateRecords instead of insertRecords in Health Connect?When you are changing records you identify by their Health Connect id rather than your own client id. Google's write guide shows…
deleteRecords: deleting Health Connect records by id, client id or time range
- Can my app delete Health Connect records that another app wrote?Not with the time-range form. Google's reference says deleteRecords with a TimeRangeFilter is automatically filtered to records belonging…
- Why does Health Connect deleteRecords throw a RemoteException?Often because an id is invalid. Google's reference says that deleting by invalid identifiers, such as a non-existing identifier, or…
- Can I delete Health Connect records using my own clientRecordId?Yes, if you set one when you inserted them. The id-based deleteRecords takes two lists, Health Connect record ids and client record ids,…
PermissionController: requesting, checking and revoking Health Connect permissions
- What does createRequestPermissionResultContract return in Health Connect?An ActivityResultContract whose input is the set of permission strings you request and whose output is a set of granted permission strings.…
- Does revokeAllPermissions take effect immediately in Health Connect?Not from the user's point of view. Google's permissions UI guide says that if you revoke permissions programmatically with…
- Why does a Health Connect app need an activity for ACTION_SHOW_PERMISSIONS_RATIONALE?Because the Health Connect permission screen links to your privacy policy and opens it inside your app. Google's get started guide says the…
- What happens after a user cancels the Health Connect permission screen twice?Google's permissions UI guide says that when the user selects Cancel on the permission request screen twice in a row, your app should show…
READ_HEALTH_DATA_IN_BACKGROUND: reading Health Connect data from a background worker
- Does Health Connect let an Android app read health data while it is in the background?Only with an extra permission. Google's sync guide says apps can only read data from Health Connect while they are in the foreground, and…
- How do I check whether background reads are supported before requesting READ_HEALTH_DATA_IN_BACKGROUND?Call healthConnectClient.features.getFeatureStatus(HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND) and compare the result…
- What does Google recommend for running Health Connect reads on a schedule?A periodic WorkManager job. Google's background-read example defines a CoroutineWorker that gets a HealthConnectClient in doWork, and…
- Can a background worker read exercise routes recorded by other apps?No. Google's exercise-routes guide says your app cannot read route data created by other apps while it runs in the background, and that…
READ_HEALTH_DATA_HISTORY: reading Health Connect data older than 30 days
- How far back can a Health Connect app read data without extra permissions?Thirty days before the moment your app was first granted any Health Connect permission. Google's read guide says all applications can read…
- Does reading old Health Connect data without the history permission throw an error?Only for single-record reads. Google's reference says an attempt to read one data point older than the window through readRecord results in…
- Can my app read its own Health Connect data from more than 30 days ago?On Android 14 and higher, yes. Google's guide says there is no historical limit on an app reading its own data on Android 14 and higher,…
- What happens to READ_HEALTH_DATA_HISTORY when a user reinstalls the app?It is gone. Google says deleting an app revokes all its permissions, including the history permission, and that after a reinstall and new…
Health Connect Metadata: recordingMethod, Device and the fields Health Connect fills in
- Why does my Health Connect record constructor fail after upgrading to connect-client 1.1.0-alpha12?Because Metadata became mandatory and can no longer be instantiated directly. Google's metadata guide says you must specify metadata…
- What is the difference between RECORDING_METHOD_ACTIVELY_RECORDED and RECORDING_METHOD_AUTOMATICALLY_RECORDED?Who started the recording. Google's reference describes actively recorded data as recorded by the user, for example an exercise session the…
- Which Health Connect Device types need the extended device types feature?Seven of them: TYPE_CONSUMER_MEDICAL_DEVICE, TYPE_GLASSES, TYPE_HEARABLE, TYPE_FITNESS_MACHINE, TYPE_FITNESS_EQUIPMENT,…
- Can I set the id or dataOrigin of a Health Connect record before inserting it?No. Google's reference says id, dataOrigin and lastModifiedTime hold sentinel values before insertion and that any value you assign is…
HealthConnectFeatures.getFeatureStatus: checking what the user's Health Connect supports
- What does getFeatureStatus return in Health Connect?An integer that is one of two constants on HealthConnectFeatures: FEATURE_STATUS_AVAILABLE, value 2, meaning the corresponding APIs can be…
- Which Health Connect features need a getFeatureStatus check?Those with a FEATURE_ constant in HealthConnectFeatures. Google's reference lists background reads, skin temperature, planned exercise,…
- What is the difference between getSdkStatus and getFeatureStatus?getSdkStatus, a companion function on HealthConnectClient, says whether Health Connect is usable on the device at all, returning…
- What should an app do when a Health Connect feature is unavailable?Hide or disable the feature and, where it can help, ask the user to update. Google's get-started guide says to ask the user to update…
Health Connect exercise routes: ExerciseRouteResult and the per-session consent flow
- Why does Health Connect return ExerciseRouteResult.ConsentRequired for a session that has a route?Because your app lacks route access for that session. Google's reference says ConsentRequired indicates a permission has not been granted…
- Can I request READ_EXERCISE_ROUTES with createRequestPermissionResultContract?No. Google's Jetpack reference says the permission cannot be granted through the standard permission request mechanism and can only be…
- How does ExerciseRouteRequestContract work?It is an ActivityResultContract whose input is the exercise session's ID from its metadata and whose output is an ExerciseRoute or null.…
- Why did updating a Health Connect exercise session delete its route?Because your app holds the route write permission and sent the session without a route. Google's exercise-routes guide says that if an app…
PlannedExerciseSessionRecord: training plans in Health Connect
- How do I link a completed workout to a Health Connect training plan?Set plannedExerciseSessionId on the ExerciseSessionRecord you write to the ID of the PlannedExerciseSessionRecord, which insertRecords…
- What is the difference between a PlannedExerciseBlock and a PlannedExerciseStep?A step is one exercise instruction, such as Google's example of eight 60 kg barbell squats, with a phase, a completion goal and optional…
- Which permissions does a training plan app need compared with a workout app in Health Connect?Google's guide splits them by role. In its heart-rate example, the app that writes plans and evaluates them needs WRITE_PLANNED_EXERCISE…
- What time does a Health Connect training plan get when created with a LocalDate?Noon on that day. Google's reference says the PlannedExerciseSessionRecord constructor that takes a startDate and a duration generates the…
Health Connect permission UI: Google's guidance for onboarding, requests and settings
- What button text does Google recommend for starting a Health Connect setup?Verb phrases such as set up or get started, or, when the button opens the permissions view, more specific text such as Choose data to…
- What happens if a user cancels the Health Connect permission screen twice?Google says that if the user selects Cancel on the permissions request screen twice in a row, your app should show a dedicated screen, and…
- What must a Health Connect onboarding activity do?Google lists five things: display relevant user education about what data is read or written, ask for consent if required, make a…
- Should an app show every Health Connect permission again when it adds a new data type?No. Google's guidance for existing integrations says only the new data types requested should be shown on the permissions screen, to avoid…
HealthKit to Health Connect: the API equivalents, call by call
- What is the Health Connect equivalent of HKObserverQuery?There is none. Apple's observer query monitors the HealthKit store and, with background delivery, HealthKit wakes the app when matching…
- Which Health Connect method replaces HKStatisticsCollectionQuery?Two methods: aggregateGroupByDuration for fixed-length buckets such as hours, and aggregateGroupByPeriod for calendar buckets such as days…
- Can a Health Connect app tell whether read permission was granted, unlike HealthKit?Yes. Apple says a HealthKit app cannot determine whether the user granted read permission, and that denied reads simply look like no data.…
- Is there a Health Connect equivalent of HKObjectQueryNoLimit?No. ReadRecordsRequest has a pageSize that defaults to 1000, and Google says that when more records match you must iterate over all pages…
Back to the Health Connect API hub, or see every question this site answers.