Get SpO2 Summary by Date
This endpoint returns the SpO2 summary data for a single date. SpO2 applies specifically to a user’s “main sleep”, which is the longest single period of time asleep on a given date.
The measurement is provided at the end of a period of sleep. The data returned usually reflects a sleep period that began the day before. For example, if you request SpO2 levels for 2021-12-22, it may include measurements that were taken the previous night on 2021-12-21 when the user fell asleep.
The data returned includes average, minimum, and maximum SpO2 levels. It uses units that correspond to the Accept-Language header provided.
Scope: oxygen_saturation
Request
| GET | /1/user/[user-id]/spo2/date/[date].json |
URI Arguments
| user-id | required | The encoded ID of the user. Use "-" (dash) for current logged-in user. |
| date | required | The date in the format yyyy-MM-dd or today. |
Request Headers
| authorization | required | Specify the token type and Fitbit user’s access token. Token type: Bearer |
| accept | optional | The media type of the response content the client is expecting. Supported: application/json |
| accept-language | optional | The measurement unit system to use for response values. See Localization. |
| accept-locale | optional | The locale to use for response values. See Localization. |
Examples
GET https
-H "accept: application/json" \
-H "authorization: Bearer <access_token>"
Response
| Element Name | Description |
| dateTime | The sleep log date specified in the format YYYY-MM-DD. |
| value : avg | The mean of the 1 minute SpO2 levels calculated as a percentage value. |
| value : min | The minimum daily SpO2 level calculated as a percentage value. |
| value : max | The maximum daily SpO2 level calculated as a percentage value. |
{
"dateTime": "2021-10-04",
"value": {
"avg": 97.5,
"min": 94.0,
"max": 100.0
}
}
Response Headers
| content-type | The media type of the response content being sent to the client. Supported: application/json |
| fitbit-rate-limit-limit | The quota number of calls. |
| fitbit-rate-limit-remaining | The number of calls remaining before hitting the rate limit. |
| fitbit-rate-limit-reset | The number of seconds until the rate limit resets. |
Note: The rate limit headers are approximate and asynchronously updated. This means that there may be a minor delay in the decrementing of remaining requests. This could result in your application receiving an unexpected 429 response if you don't track the total number of requests you make yourself.
Response Type
| HTTP Status Code | HTTP response code. List of codes are found in the Troubleshooting Guide. |
| Status Message | Description of the status code. |
| Response Body | Contains the JSON response to the API call. When errors are returned by the API call, the errorType, fieldName and message text will provide more information to the cause of the failure. |
Response Codes
| 200 | A successful request. |
| 400 | The request had bad syntax or was inherently impossible to be satisfied. |
| 401 | The request requires user authentication. |
Note: For a complete list of response codes, please refer to the Troubleshooting Guide.
Additional Information
The Single Date Summary value does not apply to a single date, necessarily, but to an SpO2 measurement taken during a period of sleep. For most users, this will span two dates to account for SpO2 levels on the date at which the summary was provided, and SpO2 levels during the previous night’s sleep.
Collecting SpO2 data
SpO2 data is collected when the user is in an extended period of sleep. There are many factors that can affect a user’s SpO2 value. Recording the data while a person is asleep allows the Fitbit device to correctly and accurately collect SpO2 data. An extended sleep period is considered to be at least 3 hours of quality sleep. In addition, data is only processed when the user is still. If a user moves too much or their sleep session is too short, this can prevent SpO2 data from processing. See help article How do I track blood oxygen saturation (SpO2) with my Fitbit device? for more information on SpO2 data processing on the Fitbit device.
The device stops collecting SpO2 data after it determines the user is awake, typically through physical movements. Once the user syncs their device, we will begin processing the SpO2 data for that sleep period. It can take up to 1 hour for the SpO2 data to be processed and made available to download.
Subscription Support for SpO2
SpO2 does not support subscription notifications (webhooks). Since SpO2 is recorded during periods of sleep, the sleep notification arrival time can be used to estimate when the SpO2 data will be available (See the "Collecting Data" section). For applications that do not track sleep, or cannot retrieve sleep data, we recommend querying the SpO2 data once or twice a day to determine if new data is available (e.g. 12 noon and midnight).
Rate limit
The SpO2 endpoints are bound by our standard rate limit. See Rate Limits.
Device compatibility
The SpO2 data is retrieved from the user’s Fitbit account. This gives the user secure and transparent control over their data. The data is then processed and made available through the API after the user syncs their device with the Fitbit data service.
Most of the current devices sold support SpO2 data collection. See the Fitbit Product page to determine if your specific device supports SpO2.
Measurement units
SpO2 measurements are calculated as percentages. This is because blood oxygen saturation levels are most commonly and easily understood by users when referred to as percentages.
