---
title: "State of Mind API: How to Read and Write Mood Data in HealthKit"
canonical: "https://aifitnessapi.com/data/state-of-mind-api"
cluster: "Health Data"
primary_query: "state of mind api"
last_reviewed: "2026-10-04"
description: "HKStateOfMind holds logged moods and emotions: a kind, a valence, labels and associations. What Apple documents, what it leaves blank, and Android's gap."
publisher: "AIFitnessAPI — independent, not sponsored"
cite_as: "\"State of Mind API: How to Read and Write Mood Data in HealthKit\", AIFitnessAPI, https://aifitnessapi.com/data/state-of-mind-api"
---

# State of Mind API: How to Read and Write Mood Data in HealthKit

> Apple HealthKit stores mood and emotion logs as HKStateOfMind samples, available from iOS 18.0, watchOS 11.0, macOS 15.0 and visionOS 2.0, and Apple's June 2024 update note says apps can read and write them. Each sample carries a kind (dailyMood or momentaryEmotion), a numeric valence, a seven-step valenceClassification, a list of labels such as anxious or calm, and a list of associations such as work or family. Apple's reference pages for these symbols give declarations only, with no stated valence range or label definitions. Google's Health Connect data types page lists no mood or emotion record; its only Wellness record is MindfulnessSessionRecord, which logs a session, not a feeling.

- Canonical: https://aifitnessapi.com/data/state-of-mind-api
- Last reviewed: 2026-10-04
- Publisher: AIFitnessAPI (https://aifitnessapi.com) — independent, not sponsored
- Cite as: "State of Mind API: How to Read and Write Mood Data in HealthKit", AIFitnessAPI, https://aifitnessapi.com/data/state-of-mind-api

---

Most pages in this cluster start with a sensor. This one starts with a person choosing a word. A State of Mind sample is a self-report: someone picks how pleasant or unpleasant they feel, tags it with emotions, and says what it relates to. No watch measures it. That makes the data easy to collect and easy to over-interpret.

## What Apple ships

Apple's HealthKit updates page, under June 2024, says apps can "Read and write mental well-being samples using the HKStateOfMind, HKPHQ9Assessment, and HKGAD7Assessment data types." The class reference gives HKStateOfMind these platforms: iOS 18.0, iPadOS 18.0, Mac Catalyst 18.0, macOS 15.0, visionOS 2.0 and watchOS 11.0. It inherits from HKSample.

| Symbol | What the declaration says | Notes |
| --- | --- | --- |
| `HKStateOfMind` | `class HKStateOfMind`, inherits from `HKSample` | One logged mood or emotion |
| `init(date:kind:valence:labels:associations:metadata:)` | `valence: Double`, `labels: [HKStateOfMind.Label]`, `associations: [HKStateOfMind.Association]`, `metadata` optional | The only initializer listed |
| `kind` | `HKStateOfMind.Kind` | Cases: `dailyMood`, `momentaryEmotion` |
| `valence` | `Double` | Range not documented |
| `valenceClassification` | `HKStateOfMind.ValenceClassification` | Seven cases: `veryUnpleasant`, `unpleasant`, `slightlyUnpleasant`, `neutral`, `slightlyPleasant`, `pleasant`, `veryPleasant`; failable `init?(valence:)` |
| `labels` | `[HKStateOfMind.Label]` | 38 cases |
| `associations` | `[HKStateOfMind.Association]` | 18 cases |
| `HKStateOfMindType` | Subclass of `HKSampleType` | Created with `HKObjectType.stateOfMindType()` |

The 38 labels are amazed, amused, angry, annoyed, anxious, ashamed, brave, calm, confident, content, disappointed, discouraged, disgusted, drained, embarrassed, excited, frustrated, grateful, guilty, happy, hopeful, hopeless, indifferent, irritated, jealous, joyful, lonely, overwhelmed, passionate, peaceful, proud, relieved, sad, satisfied, scared, stressed, surprised and worried. The 18 associations are community, currentEvents, dating, education, family, fitness, friends, health, hobbies, identity, money, partner, selfCare, spirituality, tasks, travel, weather and work.

Apple also publishes a sample project, [Visualizing HealthKit State of Mind in visionOS](https://developer.apple.com/documentation/healthkit/visualizing-healthkit-state-of-mind-in-visionos), tied to WWDC24 sessions 10083 and 10109. Its page lists iOS 18.1 and visionOS 2.1.

## What Apple leaves blank

Every symbol in the table above was fetched from Apple's documentation JSON on 2026-10-04. None of them has an abstract or a discussion. Apple does not document:

- the numeric range of `valence`, or which end is pleasant;
- the valence cut-offs behind each `ValenceClassification` case, even though `init?(valence:)` is failable and can return nil;
- what separates a `dailyMood` from a `momentaryEmotion` beyond the case names;
- what any label or association means, or how many a sample may carry.

So build defensively. Store the raw `valence` and derive any bucket yourself with `ValenceClassification(valence:)`, handling the nil case. Do not hard-code a scale from a conference slide into your UI copy until Apple puts it in the reference.

## Logged, never measured

Nothing in Apple's State of Mind reference says a device produces these samples. Each one is what a person entered, in your app, in Apple's Health app, or in another app with write access. Labels are the person's words for their state, picked from a fixed list. Treat a trend as "what this person told apps over time", not as a measurement of their mental health. If your feature summarises moods, say so on screen.

## Android has no counterpart

Google's [Health Connect data types page](https://developer.android.com/health-and-fitness/health-connect/data-types), fetched 2026-10-04, describes a Wellness category that "captures data related to a user's mental health and well-being." The only record it lists there is `MindfulnessSessionRecord`. That is an interval record whose mandatory fields are `startTime`, `endTime`, `metadata` and `mindfulnessSessionType`, with session types `MINDFULNESS_SESSION_TYPE_UNKNOWN`, `MEDITATION`, `BREATHING`, `MUSIC`, `MOVEMENT` and `UNGUIDED`. It sits behind `android.permission.health.READ_MINDFULNESS` and `WRITE_MINDFULNESS`, and the page flags `FEATURE_MINDFULNESS_SESSION` as its availability check.

A mindfulness session says someone meditated for twelve minutes. It says nothing about how they felt. The page lists no mood, emotion or valence record, so a cross-platform mood feature needs its own storage on Android. See the [MindfulnessSessionRecord reference](/health-connect/mindfulness-session-record) for that record's fields. On iOS the equivalent session type is the separate [`mindfulSession`](/healthkit/sleep-mindfulness-self-care#id-mindfulsession) category type, which is also not a mood log. [The HealthKit category values reference](/healthkit-category-values) shows why: `mindfulSession` decodes to the generic `HKCategoryValue`, so a sample says nothing beyond its time range.

| Source | Mood or emotion data | Verified from |
| --- | --- | --- |
| Apple HealthKit | `HKStateOfMind` samples, read and write | Apple HealthKit reference and updates page, fetched 2026-10-04 |
| Android Health Connect | None listed; Wellness holds only `MindfulnessSessionRecord` | Health Connect data types page, fetched 2026-10-04 |
| Wearable cloud APIs and aggregators | Not documented on our pages, so verify with each vendor | None |

## Traps

- **Another app's words.** HealthKit merges sources. A sample may come from a journaling app with different prompts from yours, so the same label can mean different things. Read the sample's source before you compare entries.
- **Journal suggestions.** Apple's authorization guide says that in iOS 17.2 and later "the Journal app encourages people to reflect on their day-to-day experiences, including physical accomplishments, workouts, emotions, and moods," and that summaries of data an app saves to HealthKit "can appear as suggestions in the Journal app, or in other apps that use the Journaling Suggestions framework." A mood your app writes can turn up somewhere the user did not expect.
- **Silent read denial.** The same guide says your app "doesn't know whether someone granted or denied permission to read data from HealthKit." An empty mood history may be a refusal. Do not tell someone they have not logged anything.
- **Labels are not a diagnosis.** Words like hopeless, anxious or overwhelmed are entries in an enum. Your app should not turn them into a clinical judgement, a risk score, or advice. If you want screening instruments, Apple ships separate types for those, covered in the [mental health assessments API](/data/mental-health-assessments-api) page, and they carry their own care requirements.

## Privacy

Mood logs reveal more than step counts. Ask for State of Mind access when the feature needs it, not at onboarding. Keep the data on the device where you can. If you sync it, encrypt it and make deletion real. Our guides on [health-data user consent](/compliance/health-data-user-consent) and [Apple's App Store health data rules](/compliance/app-store-health-data-rules) cover the consent record and the review rules that apply to every HealthKit type. None of this is legal advice.

## Before you ship

Re-read Apple's HKStateOfMind pages before each release. They may gain the range and definitions they lack today, and your bucketing code should follow them. Keep the raw valence. Label the data as self-reported everywhere it appears. On Android, plan your own store, because Health Connect has nowhere to put a mood.

## FAQ

### What fields does an HKStateOfMind sample carry?

Apple's initializer takes a date, a kind, a valence as a Double, an array of labels, an array of associations, and optional metadata. The read side adds valenceClassification. Kind has two cases, dailyMood and momentaryEmotion. The label enum has 38 cases, from amazed to worried, and the association enum has 18, from community to work. HKStateOfMind inherits from HKSample, so it also has the usual start and end dates and source. Apple's pages list these symbols without describing them, so check the declarations rather than expecting prose.

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

### What numeric range does HealthKit use for mood valence?

Apple's reference does not say. The valence property is declared as a Double and the initializer takes a Double, but the pages fetched on 2026-10-04 carry no abstract, discussion or parameter notes. HKStateOfMind.ValenceClassification has a failable init(valence:), so some values can map to no classification, yet Apple does not publish the cut-offs. Test the mapping on a device and store the raw valence alongside any bucket you derive.

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

### Is a Health Connect mindfulness session the same as a mood log?

No. Google's data types page defines MindfulnessSessionRecord as an interval record with a mindfulnessSessionType such as meditation, breathing, music, movement or unguided, behind READ_MINDFULNESS and WRITE_MINDFULNESS and the FEATURE_MINDFULNESS_SESSION availability check. It records that a session happened. It has no valence, emotion or label field, so mapping HealthKit State of Mind samples onto it would invent data that was never logged.

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

### Can mood samples my app saves to HealthKit show up in other apps?

Yes, under the user's permissions. Apple's authorization guide notes that in iOS 17.2 and later the Journal app encourages reflection on experiences including emotions and moods, and that high-level summaries of data an app saves to HealthKit can appear as suggestions in the Journal app or in other apps that use the Journaling Suggestions framework. Any app the person authorizes to read State of Mind can also query what you wrote. Tell users this before they log.

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