Medications API: Reading Medication and Dose Logs From HealthKit

Medication data on a phone comes in two shapes. One is the list a person keeps in Apple's Health app, with reminders and a tap for each dose. The other is the record a clinic holds: prescriptions, dispenses and statements in FHIR. This page covers the first. The second is covered by the HealthKit clinical records API and the Health Connect medical records API pages.

What Apple ships#

Apple's HealthKit updates page, under June 2025, says apps can "Query medications that a person has added to the Health app, using HKUserAnnotatedMedicationQueryDescriptor and the times they've logged that medication using HKMedicationDoseEventType." Every class below lists iOS 26.0, iPadOS 26.0, Mac Catalyst 26.0, macOS 26.0, visionOS 26.0 and watchOS 26.0 in Apple's reference, fetched 2026-10-04.

You query medications with HKUserAnnotatedMedicationQueryDescriptor(predicate:limit:), whose result(for:) "Returns the empty array if no HKUserAnnotatedMedication objects match." There is also the older callback-style HKUserAnnotatedMedicationQuery. Dose events are ordinary samples of HKMedicationDoseEventType, created with HKObjectType.medicationDoseEventType().

The concept, the person's copy, and the dose#

Apple splits a medication into layers, and mixing them up is the easiest bug to write.

• The concept. HKMedicationConcept is "the idea of a medication, like ibuprofen or insulin. It can have clinical significance, or can be created by the person using your app." Its identifier is "one stable identifier that stays the same across devices", which Apple suggests for checking "whether two objects represent the same medication." Its relatedCodings link it "to an external medical terminology system, such as RxNorm," and HKClinicalCoding is, in Apple's words, "closely related to the FHIR Coding model."
• The person's copy. HKUserAnnotatedMedication wraps a concept with what the person chose: a nickname that "can be edited at any point", hasSchedule (true when they "set up reminders", false when the medication is "only taken as needed", with the note that "Scheduled medications can still be taken as needed"), and isArchived, true when they move it "to the archived section in the Health App."
• The dose. HKMedicationDoseEvent points back through medicationConceptIdentifier, which "the system uses ... to link the dose event back to its HKMedicationConcept object."

Join doses to medications on the concept identifier, never on the display text or the nickname. A user-created concept may carry no codings at all, so RxNorm lookups need a fallback.

generalForm takes one of 18 HKMedicationGeneralForm values: capsule, cream, device, drops, foam, gel, inhaler, injection, liquid, lotion, ointment, patch, powder, spray, suppository, tablet, topical and unknown.

Log status is not adherence#

HKMedicationDoseEvent.LogStatus has six cases, and Apple documents each one:

Only taken says a dose was taken, and even that is what the person tapped. notInteracted and notificationNotSent describe reminders, not doses. Apple's own sample app "forms a predicate to only look for doses marked as taken." Do the same before you compute anything that looks like a rate, and do not present the result as clinical adherence.

ScheduleType tells you whether the person logged "ad-hoc, outside of any scheduled reminder" (asNeeded) or "in response to a scheduled medication reminder" (schedule). Apple documents that scheduledDate "is always non-null" for schedule and "always null" for asNeeded. doseQuantity and scheduledDoseQuantity are optional Doubles, and unit is the HKUnit the system associated with the medication at logging time.

Authorization, as far as Apple documents it#

This is the thinnest part of the reference. Apple documents HKUserAnnotatedMedicationType as "the set of authorizeable HKUserAnnotatedMedications", and that is the only authorization sentence on the medication class pages. Apple's sample project, Logging symptoms associated with a medication, adds the flow from the user's side: build and run "to see the medication list after providing authorization," and "When tapping a medication, an additional authorization sheet prompts for authorization to access symptoms data."

HealthKit does have a per-object read method, requestPerObjectReadAuthorization(for:predicate:completion:), which Apple describes as being for "a data type that requires per-object authorization (such as vision prescriptions)." The medication pages we fetched do not say whether medications use it. Apple does not document, on those pages, whether a person approves medications one at a time. Expect your app to see some medications and not others, and never assume the list is complete.

Read-only, as documented#

Apple's reference lists no initializer for HKMedicationDoseEvent, and HKUserAnnotatedMedication shows only init(coder:). The update note talks about querying. As of 2026-10-04 the documented feature is reading what the person logged in Apple's Health app. If your product needs its own dose logging, you are storing that yourself.

Symptoms are your mapping, not Apple's#

The sample project links medications to symptoms, which looks like a HealthKit feature until you read how. It "associates symptoms with these three medications using their RxNorm codes by mapping the codes to their symptoms in the SideEffects dictionary in SideEffects.swift." That table lives in the sample's source code. HealthKit does not ship side-effect data. If you build something similar, the clinical content is yours to source and defend, and it moves your app toward medical advice. Our FDA fitness app regulation page sets out where that line is usually drawn.

Android#

Google's Health Connect data types page, fetched 2026-10-04, lists no medication or dose record among its health and fitness types. Medication data appears only in Medical Records, where the Medications type maps the FHIR Medication, MedicationRequest and MedicationStatement resources behind android.permission.health.READ_MEDICAL_DATA_MEDICATIONS. Those APIs carry @ExperimentalPersonalHealthRecordApi. They hold clinical records, not reminder taps, so they are not a drop-in match for HealthKit dose events.

Privacy#

A medication list can reveal a diagnosis without naming one. Apple's guideline 5.1.3 rules on advertising and disclosure apply to it like any other HealthKit data. Ask for access when the feature needs it, keep the list on the device if you can, and never send concept names or RxNorm codes to analytics. This is engineering guidance, not legal advice.

Before you ship#

Re-check Apple's medication pages each release for write support and a fuller authorization description. Join on concept identifiers. Filter dose events on taken. Treat an empty list as "nothing shared with you", not "takes no medication".