deleteRecords: deleting Health Connect records by id, client id or time range

When a user deletes something in your app, Google's sync guide says to remove it from Health Connect too: "When a user deletes their own data from your app, make sure that the data is also removed from Health Connect." deleteRecords is how. Sources: the HealthConnectClient reference, the delete data guide, the read data guide and the synchronize data guide, all fetched October 4, 2026.

The overloads#

Two member functions on HealthConnectClient, both labelled "Added in 1.1.0":

suspend fun deleteRecords(
    recordType: KClass<Record>,
    recordIdsList: List<String>,
    clientRecordIdsList: List<String>
): Unit

suspend fun deleteRecords(
    recordType: KClass<Record>,
    timeRangeFilter: TimeRangeFilter
): Unit

And two reified extension functions in androidx.health.connect.client, which take the type as a type parameter: deleteRecords<StepsRecord>(recordIdsList = ..., clientRecordIdsList = ...) and deleteRecords<StepsRecord>(timeRangeFilter = ...). Beyond the RemoteException, SecurityException and IOException the members list, the extensions also list IllegalStateException "If service is not available."

Deleting by id#

recordIdsList is a "List of Metadata.id of Record to delete" and clientRecordIdsList a "List of client record IDs of Record to delete". The delete guide: "supply it with two lists of Strings, one for the Record IDs and one for the Client IDs. If you only have one of the IDs available, you can set emptyList() on the other list."

The exception note is the part to read twice: RemoteException covers "any IPC transportation failures. Deleting by invalid identifiers such as a non-existing identifier or deleting the same record multiple times will result in IPC failure." Google's read guide gives the same case as its RemoteException example: an app "trying to delete a record with a given uid", where the exception "is thrown after the app finds out upon checking in the underlying service that the record doesn't exist." Its advice: "Perform regular syncs between your app's datastore and Health Connect" and "Apply retries and backoff strategies".

Deleting by time range#

The time-range form takes a TimeRangeFilter, whose between is "inclusive-exclusive". Google does not document whether a record that starts before the range and ends inside it is deleted. If exact boundaries matter, read the records first and delete by id.

Whose records you can delete#

For the time-range form, Google is explicit: the deletion is "automatically filtered to Record belonging to the calling application". For the id-based form, neither the reference nor the delete guide says what happens if an id belongs to a record another app wrote. Pass only ids your app received from insertRecords, or client ids your app assigned. Records the user deletes from inside Health Connect reach you the other way, as DeletionChange entries from getChanges.

A sketch#

suspend fun deleteWeightsFromHealthConnect(
    client: HealthConnectClient,
    healthConnectIds: List<String>,
    clientIds: List<String>
) {
    try {
        client.deleteRecords(
            recordType = WeightRecord::class,
            recordIdsList = healthConnectIds.distinct(),
            clientRecordIdsList = clientIds.distinct()
        )
    } catch (e: RemoteException) {
        // One unknown or already-deleted id fails the whole transaction.
        // Re-sync your stored ids with Health Connect, then retry with the rest.
    }
}

suspend fun deleteMyStepsForDay(client: HealthConnectClient, day: LocalDate) {
    client.deleteRecords(
        StepsRecord::class,
        timeRangeFilter = TimeRangeFilter.between(day.atStartOfDay(), day.plusDays(1).atStartOfDay())
    )
}

RemoteException here is android.os.RemoteException. distinct() matters because the reference counts "deleting the same record multiple times" as an invalid request.

Pitfalls#

• Duplicate ids in one call. A list that contains the same id twice fails the whole transaction.
• Retrying a delete that already worked. If the first attempt succeeded and only the acknowledgement was lost, the retry passes ids that no longer exist, which also fails. Re-check what still exists before retrying.
• One record type per call. Every overload takes a single recordType. A user deleting a workout may mean several calls, one per type you wrote for it.
• Client ids you never set. clientRecordIdsList only matches records inserted with a clientRecordId, covered on the clientRecordId upsert page.
• Permissions. The reference lists SecurityException "For requests with unpermitted access" but does not name the permission each delete needs on that page. Check the record's permissions on its page in the Health Connect record reference.

The obligations behind deletion, and how to test it, are covered in health data retention and deletion, data deletion and export and testing data deletion.