readRecords and ReadRecordsRequest: paging with pageSize and pageToken

readRecords is the raw-records read in the Health Connect Jetpack client. It hands back records one page at a time, and the loop that walks those pages is where most of the bugs live. This page covers the request, the response and the paging loop, from Google's ReadRecordsRequest reference, its ReadRecordsResponse reference and the read data guide, all fetched October 4, 2026. Setup and the permission request are covered in the Google Health Connect integration guide.

The method and the request#

The declaration on HealthConnectClient is suspend fun <T : Record> readRecords(request: ReadRecordsRequest<T>): ReadRecordsResponse<T>, and Google's one-line summary is "Retrieves a collection of Records." The reference lists three exceptions: RemoteException "For any IPC transportation failures", SecurityException "For requests with unpermitted access" and IOException "For any disk I/O issues." The Health Connect error codes page collects every exception type the HealthConnectClient reference documents and counts the methods each appears on.

The request's constructor, with the defaults the reference shows:

ReadRecordsRequest(
    recordType: KClass<T>,
    timeRangeFilter: TimeRangeFilter,
    dataOriginFilter: Set<DataOrigin> = emptySet(),
    ascendingOrder: Boolean = true,
    pageSize: Int = 1000,
    pageToken: String? = null
)

The class description explains the paging contract: "Returned collection will contain a ReadRecordsResponse.pageToken if number of records exceeds pageSize. Use this if you expect an unbound number of records within specified time ranges."

Availability. The reference labels HealthConnectClient, ReadRecordsRequest and ReadRecordsResponse "Added in 1.1.0", in the androidx.health.connect:connect-client artifact. The readRecords method carries no label of its own.

The response, and the token that is not always null#

ReadRecordsResponse has two properties: records, "a collection of records", and pageToken: String?, which the reference describes as "an optional page token to use for ReadRecordsRequest.pageToken in the next request if more records can be fetched; contains value null if no more pages."

Google's read guide qualifies that in a note:

"Depending on the specific system or Health Connect APK version (such as on Android 12 and 13 or across specific IPC serialization boundaries), ReadRecordsResponse.pageToken can return an empty string "" instead of null when pagination is complete. To reliably check whether pagination is complete, use isNullOrEmpty() rather than checking only for null."

The guide's own paging sample, a few lines further down, still ends its loop with while (pageToken != null). Follow the note, not the sample.

A paging loop#

suspend fun readAllHeartRate(
    client: HealthConnectClient,
    start: Instant,
    end: Instant
): List<HeartRateRecord> {
    val all = mutableListOf<HeartRateRecord>()
    var pageToken: String? = null
    do {
        val page = client.readRecords(
            ReadRecordsRequest(
                recordType = HeartRateRecord::class,
                timeRangeFilter = TimeRangeFilter.between(start, end),
                pageToken = pageToken
            )
        )
        all += page.records
        pageToken = page.pageToken
    } while (!pageToken.isNullOrEmpty())
    return all
}

Collecting everything into one list keeps the sketch short; for a long range, process each page as it arrives. Google recommends using pageToken "to retrieve all available data from the requested time period", and in the same breath warns to "be careful to avoid rate-limiting concerns." Its sample wraps the loop in a catch (quotaError: IllegalStateException) with a comment saying to back off. Retrying from the failed page is covered in Health Connect rate limit exceeded.

Reading one record by id#

If you stored a record's Metadata.id, you do not need a range query. readRecord(recordType, recordId) "Reads one Record point with its recordType and recordId", and the reified extension readRecord<T>(recordId) does the same with the type as a type parameter. The reference notes that an invalid identifier "will result in IPC failure", a RemoteException.

When readRecords is the wrong call#

Google is direct about the first row: "For cumulative types like StepsRecord, use aggregate() instead of readRecords() to avoid double counting from multiple sources and improve accuracy."

Pitfalls#

• Ending the loop on null only. On the versions Google's note describes, the last page carries "". A != null check keeps looping and sends an empty string back as the page token. Google does not document what Health Connect returns for that request; isNullOrEmpty() avoids finding out.
• Adding up raw step records. Several apps can write steps for the same minutes, and a loop over readRecords results counts all of them. Ask aggregate for the total.
• Changing the request between pages. Google does not document what a page token means if the time range, filters, order or page size change between calls. Its sample changes only pageToken; do the same.
• Assuming a maximum pageSize. The reference shows the default of 1000 and no upper bound for reads. getChanges documents a range of 1 to 5000 for its own pageSize, which says nothing about this one.
• Reading the sort order into ascendingOrder. The reference documents only its default. It does not say which timestamp the ordering uses, so if order matters, check it against your data.
• An empty page is not an error. No records can mean nothing was written in the window or a dataOriginFilter that leaves out the app that wrote the data. Health Connect returns no data separates the common cases, including the default 30-day read limit, and Health Connect SecurityException covers the permission failures.