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.
