Is missing HRV or sleep data on some dates expected behavior in the Fitbit Web API?

[yuta-naka-dev]

Hello Fitbit Web API Community,

We are currently evaluating the Fitbit Web API for a production use case, and we are trying to understand whether some missing daily data patterns are normal Fitbit behavior or a sign that our integration approach needs to be improved.

I understand there is no guaranteed support or SLA for the Web API. I’m mainly looking for clarification from others who have worked with these endpoints in real-world usage.

Our setup
- OAuth scopes:
- profile
- activity
- heartrate
- sleep
- respiratory_rate
- Endpoints we call per date:
- /1.2/user/-/sleep/date/{date}.json
- /1/user/-/activities/heart/date/{date}/1d.json
- /1/user/-/hrv/date/{date}.json
- /1/user/-/br/date/{date}.json
- User timezone: Asia/Tokyo
- We store the raw response per date and can manually re-fetch historical dates

What we observed
For one user, we checked a recent 7-day window.

Before re-fetching, our stored raw data showed:
- sleep data on 6 out of 7 dates
- resting heart rate on 6 out of 7 dates
- HRV on 4 out of 7 dates
- breathing rate on 2 out of 7 dates
- one specific day had no raw data at all, even though surrounding dates had usable data

We then manually re-fetched the same 7-day period again.

After the re-fetch:
- the same missing day was still missing
- almost all stored raw payloads were identical before and after the re-fetch
- the only small difference we noticed was a non-essential heartRateZones caloriesOut value in one heart rate payload
- the core values we actually care about did not change

Because of this, it seems unlikely that the missing day was caused by a temporary API outage or a transient fetch failure on our side. It looks more like the data simply was not available from Fitbit for that date.

Additional context
We also compared data from the same Fitbit device through another platform integration. That comparison did not clearly show one side being better, because each side seemed to have missing values on different dates or for different metrics.

So at this point, our main question is no longer which integration is better, but rather:
- what level of missing HRV or sleep data is considered normal from Fitbit itself
- and under what conditions those values are expected to be absent

Questions
1. Is it expected that /hrv/date/{date}.json returns no usable value on some dates even when resting heart rate and/or sleep data exists for the same date?
2. Is it normal that one day remains missing even after manually re-fetching the same recent period?
3. If a day is still missing after a manual re-fetch several days later, should we generally treat that day as permanently unavailable rather than delayed?
4. Are there documented conditions for HRV availability, such as:
- overnight wear requirements
- sleep stage quality or minimum sleep duration
- device model limitations
- sync timing
- Fitbit-side post-processing delay
5. Is it normal for sleep/date/{date}.json or hrv/date/{date}.json to be missing for a date even when adjacent dates are present?
6. Are there known cases where resting heart rate is available but HRV is not? If so, what usually causes that?

Our goal is to avoid misclassifying expected Fitbit-side missing data as an integration bug on our side.

Any clarification, documentation, or similar experiences would be greatly appreciated.

Thank you.

[DorisFitbit]

Hi @yuta-naka-dev 

Thank you for your patience and the detailed inquiry. The patterns you are observing are consistent with Fitbit’s data processing logic. In most cases, missing data for a specific date is a result of the backend algorithm's inability to calculate a metric due to data quality, rather than an integration error.

Below are the specific answers to your questions:

1. Discrepancy between HRV/BR and RHR/Sleep:

Yes, this is expected. HRV and Breathing Rate (BR) have much higher data quality requirements than Resting Heart Rate (RHR) or basic sleep logs.

2. 3. Handling Missing Days and Re-fetching:

Yes, this is normal. If a data point is missing after a re-fetch of a historical date, it indicates the data was never created on the backend.

4. Conditions for Data Availability:

Several factors can prevent the calculation of HRV/BR, even if the device was worn. As a troubleshooting standard, if the data is missing in the Fitbit Mobile App, it will not be available via the Web API. If the data is in the app but missing in the API, please report that as a bug. Alternative Verification: You may also query the Google Health API; if the data is missing there as well, it confirms the issue lies in the raw data collection.

• Here is the Google Health API migration guide: https://developers.devsite.corp.google.com/health/migration?db=home-features&hl=en 
• For more on how these values are processed, see the Collecting HRV Data
• You may also check out Fitbit Help Center for proper wearing guidelines.

5. Missing Data on Adjacent Dates: 

Yes, this is normal. Biometric data is dependent on daily user behavior (e.g., forgetting to wear the device, battery depletion, or restless sleep), which frequently results in gaps between successful days.

6. RHR Available but HRV Missing:

Yes, this is a common. The primary reason is that RHR and HRV are handled by entirely different algorithms with different data quality thresholds. It is not a single process that calculates all metrics simultaneously. We always recommend checking the Fitbit Mobile App. If the HRV value is missing in the app, it confirms the data was not calculated by the backend. If the value is present in the app but missing via the Web API, please report this as it may indicate an integration issue.

Hope it helps! Please let me know if you have any further questions.