getChanges and getChangesToken: incremental sync from Health Connect

Re-reading a whole window to find out what changed misses deletions and wastes calls. Health Connect's changes API gives you a cursor instead. This page covers the token, the paging loop and the two kinds of change, from the HealthConnectClient reference, the ChangesTokenRequest, ChangesResponse, UpsertionChange and DeletionChange references, and the synchronize data guide, all fetched October 4, 2026. What to do when a token has expired is a separate page: Health Connect changesTokenExpired.

Getting a token#

suspend fun getChangesToken(request: ChangesTokenRequest): String returns a token "representing a point in time in the underlying Android Health Platform". Google: "Changes-tokens represent a point in time after which the client is interested in knowing the changes for a set of interested types of Record and optional DataOrigin filters."

ChangesTokenRequest(
    recordTypes: Set<KClass<Record>>,
    dataOriginFilters: Set<DataOrigin> = setOf()
)

recordTypes is the "Set of Record types the token will observe change for", and dataOriginFilters is "Optional set of DataOrigin filters, default is empty set for no filter."

Google's guide recommends one token per type, for a stated reason: "We recommend getting separate tokens per data type instead of getting them in bulk to avoid having an Exception in case one of the permissions is revoked." Its best-practices section adds: "Only use a list of multiple data types with the Changes Sync API if these data types are either consumed together or not at all."

Reading changes#

There are two overloads:

suspend fun getChanges(changesToken: String): ChangesResponse
suspend fun getChanges(changesToken: String, pageSize: @IntRange(from = 1, to = 5000) Int): ChangesResponse

The first one's contract: "The response returned may not provide all the changes due to IPC or memory limits, see ChangesResponse.hasMore. Clients can make more api calls to fetch more changes from Health Connect with updated ChangesResponse.nextChangesToken." For the second, pageSize "is a soft limit that serves as a recommendation to the system", and "in certain cases the response might exceed the pageSize." Both list RemoteException and SecurityException.

Change is an interface with two implementations. UpsertionChange is "A Change with inserted or updated Record", exposed as record. DeletionChange exposes only recordId, and the reference explains why: "For privacy, only unique identifiers of the deletion are returned." All of these classes are labelled "Added in 1.1.0" in the reference; the two getChanges overloads and getChangesToken carry no label of their own.

A sync pass for one record type#

suspend fun pullWeightChanges(
    client: HealthConnectClient,
    savedToken: String,
    ownPackage: String,
    store: WeightStore // your persistence
): String {
    var token = savedToken
    do {
        val response = client.getChanges(token)
        if (response.changesTokenExpired) {
            throw TokenExpired() // your type; recover as the expired-token page describes
        }
        for (change in response.changes) {
            when (change) {
                is UpsertionChange ->
                    if (change.record.metadata.dataOrigin.packageName != ownPackage) {
                        store.upsert(change.record.metadata.id, change.record as WeightRecord)
                    }
                is DeletionChange -> store.deleteByHealthConnectId(change.recordId)
            }
        }
        token = response.nextChangesToken
    } while (response.hasMore)
    return token // persist only after the changes above are applied
}

The structure follows Google's processChanges sample. The token used for the first pass comes from getChangesToken(ChangesTokenRequest(recordTypes = setOf(WeightRecord::class))). Taking that token before your initial full read, so writes made during the read appear in the first getChanges, is our ordering; Google's guide does not prescribe one.

Skipping your own writes, and why ids matter#

• Your own upserts. Google's steps say: "For UpsertionChange, only take changes that didn't come from the calling app to make sure you're not re-importing data." Its sample compares change.record.metadata.dataOrigin.packageName with the app's package name.
• What to key on. "For UpsertionChange, use the id and the lastModifiedTime from its metadata to upsert the record. For DeletionChange, use the id provided to delete the record."
• Store ids when you write. "If your app needs to read data from Health Connect, you must store the id. This is necessary to correctly process deletion changelogs, as DeletionChange notifications only provide the record id." The ids come back from insertRecords, covered on the clientRecordId upsert page.
• Deletions have no type. Because a DeletionChange omits the record type, Google says "you can either specify only 1 data type for each call of getChanges, or make sure that you've stored this information separately beforehand."

When to call it#

The sync guide is plain about the limits: "As your app can't get notified of new data, check for new data at two points": each time the app comes to the foreground, and periodically while it stays there. Reading in the background takes an extra permission the user must grant. Tokens do not last: getChangesToken's reference says they "are only valid for 30 days after they're generated", so a user who does not open the app for a month will hand you an expired one. The design behind cursor-based sync on both platforms is in incremental sync, and a tested version of the bookkeeping is the incremental sync anchor recipe.

Pitfalls#

• Saving the token before applying the batch. If the app dies between saving nextChangesToken and writing the changes, those changes are gone. Save it after.
• One token for several independent types. Google recommends separate tokens "to avoid having an Exception in case one of the permissions is revoked."
• Re-importing your own data. Without the dataOrigin check, every record you write comes back to you as an upsert.
• Not storing Health Connect ids. Without them, a DeletionChange cannot be matched to anything you hold.
• Treating pageSize as exact. It is a soft limit; size your processing for responses larger than requested.
• Reading changesTokenExpired as "no changes". It is a flag on a normal response, not an exception. The recovery is on the expired token page.