READ_HEALTH_DATA_HISTORY: reading Health Connect data older than 30 days

The first time a Health Connect app tries to import a user's year of runs, it usually gets about a month. That is not a bug in the read: Health Connect limits how far back an app can see unless it holds one extra permission. This page covers the default window, the permission that lifts it, and the cases Google documents where the limit applies differently.

The default window, in Google's words#

Google's "Read raw data" guide: "By default, all applications can read data from Health Connect for up to 30 days prior to when any permission was first granted."

The get-started guide repeats it in an Important box: "Health Connect can read data for up to 30 days prior to the time permission was granted. If you would like your app to read records beyond 30 days, use the PERMISSION_READ_HEALTH_DATA_HISTORY permission."

The anchor is the moment your app first received any Health Connect permission, not today. An app connected on 1 March can read back to the end of January, and still only that far a year later.

What the permission is#

The Jetpack reference lists the methods it governs: "HealthConnectClient.readRecord, HealthConnectClient.readRecords, HealthConnectClient.aggregate, HealthConnectClient.aggregateGroupByPeriod, HealthConnectClient.aggregateGroupByDuration and HealthConnectClient.getChanges." Like the background permission, it is one grant for every type, layered on top of the per-type read permissions you already hold.

What happens without it#

The reference is more precise than the guide. Without the permission:

• "Any attempt to read a single data point, via HealthConnectClient.readRecord, older than 30 days from before the first HealthConnect permission was granted to the calling app, will result in an error."
• "Any other read attempts will not return data points older than 30 days from before the first HealthConnect permission was granted to the calling app."

So a single-record read by ID fails loudly, while readRecords, the aggregates and getChanges quietly leave the older data out. The read guide's own summary, "without this permission, an attempt to read records older than 30 days results in an error", is broader than the reference. Handle both: catch the error on readRecord, and do not treat a short result from the other methods as proof that no older data exists.

Your own data follows different rules#

Google's guide has a section on reading data your app wrote earlier, aimed at resyncing after a reinstall, with these limits:

To read your own history, Google says "you need to indicate the package name as a DataOrigin object in the dataOriginFilter parameter of your ReadRecordsRequest." The guide then adds: "The restrictions can be removed by requesting a Read permission." It does not name the permission there, but the next section does: "If you need to extend read permissions beyond any of the default restrictions, request the PERMISSION_READ_HEALTH_DATA_HISTORY."

Check the feature, then request#

The Jetpack reference: "This feature is dependent on the version of HealthConnect installed on the device. To check if it's available call HealthConnectFeatures.getFeatureStatus and pass HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_HISTORY as an argument." The constant is 4, added in 1.1.0. The pattern follows Google's reference sample:

val requestHistory = activity.registerForActivityResult(
    PermissionController.createRequestPermissionResultContract()
) { granted: Set<String> ->
    if (HealthPermission.PERMISSION_READ_HEALTH_DATA_HISTORY in granted) {
        // data older than 30 days is readable from now on
    } else {
        // stay inside the default window
    }
}

if (healthConnectClient.features.getFeatureStatus(
        HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_HISTORY
    ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE
) {
    requestHistory.launch(setOf(HealthPermission.PERMISSION_READ_HEALTH_DATA_HISTORY))
}

Once granted, a backfill is an ordinary paged read over a long window. ReadRecordsRequest defaults to a pageSize of 1000, so loop on pageToken as described on the readRecords pagination page, and see historical backfill for chunking and checkpointing a long import.

Uninstalling resets the clock#

Google: "If a user deletes your app, all permissions, including the history permission, are revoked. If the user reinstalls your app and grants permission again, the same default restrictions apply, and your app can read data from Health Connect for up to 30 days prior to that new date." Its example: an app deleted on May 10, 2023, reinstalled on May 15 and granted read permissions can by default read back only to April 15, 2023.

Pitfalls#

• Long-range totals come back low, without an error. An aggregate over a year returns only what falls inside the window, so a yearly step total can be a monthly one. Check whether the history permission is granted before showing long-range figures.
• Two different 30-day limits. The history window counts back from the first permission grant. Changes tokens are a separate limit: the reference says they "are only valid for 30 days after they're generated". Losing a token is covered by changes token expired.
• Requesting without the feature check. On a Health Connect build without the feature, there is nothing to grant. Google's sample only launches the request after getFeatureStatus returns FEATURE_STATUS_AVAILABLE; the check is explained on the getFeatureStatus page.
• Assuming your own data is always readable. It is only on Android 14 and higher, and only when you filter by your own package in dataOriginFilter.
• Background reads do not widen the window. READ_HEALTH_DATA_IN_BACKGROUND governs when you may read, not how far back. A worker importing old data needs both grants.
• An empty result is not the same as no data. Missing permissions, the history window and a filter that matches nothing all look alike; Health Connect returns no data walks through telling them apart.