---
title: "deleteRecords: deleting Health Connect records by id, client id or time range"
canonical: "https://aifitnessapi.com/health-connect-api/deleterecords"
cluster: "Health Connect API"
primary_query: "HealthConnectClient.deleteRecords"
last_reviewed: "2026-10-04"
description: "Health Connect's deleteRecords by record id, client record id or TimeRangeFilter: whose records each form can touch, and why one bad id fails the batch."
publisher: "AIFitnessAPI — independent, not sponsored"
cite_as: "\"deleteRecords: deleting Health Connect records by id, client id or time range\", AIFitnessAPI, https://aifitnessapi.com/health-connect-api/deleterecords"
---

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

> HealthConnectClient.deleteRecords comes in two forms: one takes a record type plus a list of Health Connect record ids and a list of your client record ids, the other takes a record type and a TimeRangeFilter. Google's reference says the time-range form is automatically filtered to records belonging to the calling app, and that both forms run as a transaction, so if one deletion fails none is applied. Deleting a non-existent id, or the same record twice, causes an IPC failure for the whole call.

- Canonical: https://aifitnessapi.com/health-connect-api/deleterecords
- Last reviewed: 2026-10-04
- Publisher: AIFitnessAPI (https://aifitnessapi.com) — independent, not sponsored
- Cite as: "deleteRecords: deleting Health Connect records by id, client id or time range", AIFitnessAPI, https://aifitnessapi.com/health-connect-api/deleterecords

---

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](https://developer.android.com/reference/kotlin/androidx/health/connect/client/HealthConnectClient), the [delete data guide](https://developer.android.com/health-and-fitness/health-connect/delete-data), the [read data guide](https://developer.android.com/health-and-fitness/health-connect/read-data) and the [synchronize data guide](https://developer.android.com/health-and-fitness/health-connect/sync-data), all fetched October 4, 2026.

## The overloads

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

```kotlin
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."

| Form | What Google says it deletes |
| --- | --- |
| By ids | "Deletes one or more `Record` by their identifiers. Deletion of multiple `Record` is executed in single transaction - if one fails, none is deleted." |
| By time range | "Deletes any `Record` of the given `recordType` in the given `timeRangeFilter` (automatically filtered to `Record` belonging to the calling application). Deletion of multiple `Record` is executed in a transaction - if one fails, none is deleted." |

## 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](/health-connect-api/getchanges-incremental-sync).

## A sketch

```kotlin
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](/health-connect-api/insertrecords-clientrecordid-upsert).
- **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](/health-connect).

The obligations behind deletion, and how to test it, are covered in [health data retention and deletion](/compliance/health-data-retention-deletion), [data deletion and export](/architecture/data-deletion-and-export) and [testing data deletion](/test/data-deletion).

## FAQ

### 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 to the calling application. For the form that takes record ids and client record ids, neither the reference nor Google's delete guide says what happens when an id belongs to another app's record, so the safe practice is to pass only ids your own app inserted.

[Permalink](https://aifitnessapi.com/health-connect-api/deleterecords#faq-1)

### 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 deleting the same record multiple times results in an IPC failure, and because the deletion runs as a single transaction, nothing in that call is deleted. Remove duplicates from the id lists, re-sync your stored ids with Health Connect, and retry with the ids that still exist.

[Permalink](https://aifitnessapi.com/health-connect-api/deleterecords#faq-2)

### 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, and Google's delete guide says that if you only have one kind of id you can pass emptyList() for the other. Records inserted without a clientRecordId can only be deleted by their Health Connect id or by time range.

[Permalink](https://aifitnessapi.com/health-connect-api/deleterecords#faq-3)