---
title: "Medications API: Reading Medication and Dose Logs From HealthKit"
canonical: "https://aifitnessapi.com/data/medications-api"
cluster: "Health Data"
primary_query: "healthkit medications api"
last_reviewed: "2026-10-04"
description: "HealthKit's iOS 26 Medications API reads the medications a person tracks in Health and their dose logs. Fields, log statuses, RxNorm codes, Android's gap."
publisher: "AIFitnessAPI — independent, not sponsored"
cite_as: "\"Medications API: Reading Medication and Dose Logs From HealthKit\", AIFitnessAPI, https://aifitnessapi.com/data/medications-api"
---

# Medications API: Reading Medication and Dose Logs From HealthKit

> Apple's Medications API, available from iOS 26.0, watchOS 26.0 and macOS 26.0, lets an app query the medications a person has added to the Health app and the doses they logged. Each tracked medication is an HKUserAnnotatedMedication holding an HKMedicationConcept with a display name, a manufactured form and clinical codings such as RxNorm, and each logged dose is an HKMedicationDoseEvent with a log status such as taken, skipped or snoozed. Apple describes the API as query access and its reference lists no initializer for creating dose events. Google's Health Connect data types page has no medication-logging record; medication data on Android lives only in the experimental Medical Records FHIR API.

- Canonical: https://aifitnessapi.com/data/medications-api
- Last reviewed: 2026-10-04
- Publisher: AIFitnessAPI (https://aifitnessapi.com) — independent, not sponsored
- Cite as: "Medications API: Reading Medication and Dose Logs From HealthKit", AIFitnessAPI, https://aifitnessapi.com/data/medications-api

---

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](/data/clinical-records-api) and the [Health Connect medical records API](/data/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.

| Class | What Apple says it is | Key properties |
| --- | --- | --- |
| `HKUserAnnotatedMedication` | "A reference to the tracked medication and the details a person can customize." | `medication`, `nickname`, `hasSchedule`, `isArchived` |
| `HKMedicationConcept` | "An object that describes a specific medication concept." | `identifier`, `displayText`, `generalForm`, `relatedCodings` |
| `HKMedicationDoseEvent` | A sample (inherits from `HKSample`); no abstract | `logStatus`, `scheduleType`, `scheduledDate`, `doseQuantity`, `scheduledDoseQuantity`, `unit`, `medicationConceptIdentifier` |
| `HKMedicationDoseEventType` | "Represents a recorded log of a specific medication, represented by HKMedicationDoseEvent samples." | Subclass of `HKSampleType` |
| `HKUserAnnotatedMedicationType` | "Represents the set of authorizeable HKUserAnnotatedMedications." | Subclass of `HKObjectType`, not `HKSampleType` |
| `HKClinicalCoding` | "A clinical coding that represents a medical concept using a standardized coding system." | `system`, `version`, `code` |

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:

| Case | Apple's description |
| --- | --- |
| `taken` | "The person logs that they took the medication dose." |
| `skipped` | "The person logs that they skipped the medication dose." |
| `snoozed` | "The person snoozes a scheduled medication notification." |
| `notInteracted` | "The person doesn't interact with a scheduled medication reminder." |
| `notLogged` | "The person undoes a previously logged medication status." |
| `notificationNotSent` | "The system assigns this status when it fails to deliver a scheduled medication notification." |

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](https://developer.apple.com/documentation/healthkit/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](/compliance/fda-fitness-app-regulation) page sets out where that line is usually drawn.

## Android

Google's [Health Connect data types page](https://developer.android.com/health-and-fitness/health-connect/data-types), fetched 2026-10-04, lists no medication or dose record among its health and fitness types. Medication data appears only in [Medical Records](https://developer.android.com/health-and-fitness/health-connect/medical-records/data-format), 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.

| Source | Medication list and dose logs | Verified from |
| --- | --- | --- |
| Apple HealthKit Medications API | `HKUserAnnotatedMedication` and `HKMedicationDoseEvent`, query access | Apple HealthKit reference and updates page, fetched 2026-10-04 |
| Apple HealthKit clinical records | `medicationRecord` FHIR resources from a provider | See [clinical records API](/data/clinical-records-api) |
| Android Health Connect | No dose-logging record; FHIR medications only via experimental Medical Records | Health Connect data types and medical records data format pages, fetched 2026-10-04 |
| Wearable cloud APIs and aggregators | Not documented on our pages, so verify with each vendor | None |

## Privacy

A medication list can reveal a diagnosis without naming one. Apple's [guideline 5.1.3](/compliance/app-store-guideline-5-1-3-health-research) 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".

## FAQ

### What does HKMedicationDoseEvent.LogStatus record?

It records what happened to a dose, in six cases Apple documents. taken and skipped are what the person logged. snoozed means they snoozed a scheduled notification. notInteracted means they did not interact with a scheduled reminder. notLogged means they undid a status they had logged earlier. notificationNotSent is assigned by the system when it fails to deliver a scheduled notification. Only taken means a dose was taken, so filter on it before counting adherence.

[Permalink](https://aifitnessapi.com/data/medications-api#faq-1)

### How does Apple authorize access to Health app medications?

Apple's reference says little. HKUserAnnotatedMedicationType is documented as representing the set of authorizeable HKUserAnnotatedMedications, and Apple's sample project describes seeing the medication list after providing authorization, then a separate authorization sheet when it asks for symptom data. The pages we fetched do not say whether a person approves medications one at a time or as a group. Test the flow on a device and design for a partial list.

[Permalink](https://aifitnessapi.com/data/medications-api#faq-2)

### Can an app write medication doses into HealthKit?

Apple's reference lists no initializer for HKMedicationDoseEvent, and HKUserAnnotatedMedication shows only init(coder:). The June 2025 update note frames the feature as querying medications a person added to the Health app and the times they logged them. On the documentation as fetched on 2026-10-04, this is a read API. Logging happens in Apple's Health app, so build your feature around reading those logs.

[Permalink](https://aifitnessapi.com/data/medications-api#faq-3)

### Does Health Connect have a medication logging data type?

Not for dose logging. Google's data types page lists no medication or dose record among the health and fitness types. Medication data appears only in Medical Records, where the Medications category maps the FHIR Medication, MedicationRequest and MedicationStatement resources behind android.permission.health.READ_MEDICAL_DATA_MEDICATIONS. Those APIs carry the ExperimentalPersonalHealthRecordApi annotation, and a FHIR MedicationStatement is a clinical record, not a tap on a reminder.

[Permalink](https://aifitnessapi.com/data/medications-api#faq-4)