Time Series
This endpoint returns a time series for a given metric with automatic merge strategy selection. The system chooses the optimal merge method based on metric characteristics to ensure the best data quality without manual configuration.
Request Example
{
"from_timestamp": "2024-01-01T00:00:00Z",
"to_timestamp": "2024-01-02T00:00:00Z",
"metric": "heartrate"
}
Response Example
{
"metric": "heartrate",
"start_at": "2024-01-01T00:00:00Z",
"offsets": [0, 60000, 120000],
"durations": [60000, 60000, 60000],
"values": [100, 150, 200],
"providers": ["garmin"]
}
The arrays offsets, durations, and values will all be of the same length. This alignment is crucial for interpreting the data correctly.
Overriding the Default Merge Method
To override the default merge strategy, use the merge_method parameter.
The default merge method is automatically selected based on the metric type and provides optimal data quality for most use cases. Only override the default if you have specific requirements that cannot be met by the automatic selection. This parameter is intended for advanced users who understand the implications of different merge strategies.
Source Selection Methods
Selects data from a single best provider source based on criteria like coverage, granularity, or priority. Only one source contributes to the final result, ensuring consistency but potentially losing data from other sources.
-
select_best_weighted_source: Best weighted coverage score mix of time coverage and data point density -
select_highest_coverage_source: Highest total time coverage (sum of all entry durations) -
select_most_granular_source: Most data points (highest entry count) -
select_highest_priority_source_type: Sample > Intraday > Summary > Activity priority, then weighted coverage
Coverage Optimization Methods
Maximizes time coverage by selecting non-overlapping entries from multiple sources. Prioritizes filling time gaps while avoiding overlaps, using interval scheduling algorithms.
-
merge_maximize_coverage: Weighted interval scheduling to maximize total time coverage -
merge_maximize_granularity: Source with most data points, then greedy interval scheduling -
merge_maximize_weighted_coverage: Source with best weighted coverage score, then greedy interval scheduling
Sample Merging Methods
Combines all sample data points, resolving conflicts at identical timestamps by selecting the source with the most total entries. Preserves all available data while handling timestamp collisions.
merge_all_samples: All zero-duration samples, conflicts resolved by source with most total entries
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
Start time of the query range in UTC, inclusive
End time of the query range in UTC, non-inclusive
The metric you want to query
heartrate_max, heartrate_min, heartrate_zone0_duration, heartrate_zone1_duration, heartrate_zone2_duration, heartrate_zone3_duration, heartrate_zone4_duration, heartrate_zone5_duration, heartrate, heartrate_resting, heartrate_resting_min, heartrate_resting_max, hrv_rmssd, hrv_sdnn, elevation_max, elevation_min, elevation_gain, elevation_loss, ascent, descent, calories_burned_active, calories_burned_basal, calories_burned, calories_intake, steps, floors_climbed, distance, distance_walking, distance_cycling, distance_running, distance_wheelchair, distance_swimming, speed, speed_max, speed_min, air_temperature_max, air_temperature, air_temperature_min, spo2, spo2_max, spo2_min, breathing_rate, breathing_rate_min, breathing_rate_max, longitude, latitude, elevation, duration_active, swimming_lengths, swimming_distance_per_stroke, sleep_efficiency, sleep_duration, sleep_duration_deep, sleep_duration_light, sleep_duration_rem, sleep_duration_awake, bedtime_duration, sleep_interruptions, sleep_duration_nap, sleep_score, sleep_breathing_rate, sleep_breathing_rate_min, sleep_breathing_rate_max, sleep_latency, wakeup_latency, cadence, cadence_min, cadence_max, pace, body_mass_index, weight, height, vo2max, body_temperature, body_temperature_max, body_temperature_min, basal_body_temperature, basal_body_temperature_max, basal_body_temperature_min, skin_temperature, skin_temperature_max, skin_temperature_min, sleep_skin_temperature_deviation, ecg_voltage, ecg_rri, body_fat, body_fat_min, body_fat_max, blood_pressure_systolic, blood_pressure_systolic_min, blood_pressure_systolic_max, blood_pressure_diastolic, blood_pressure_diastolic_min, blood_pressure_diastolic_max, body_bone_mass, glucose strava, health_connect, fitbit, garmin, huawei, dexcom, whoop, withings, suunto, apple, freestyle_libre, oura, polar, coros, ultrahuman, samsung_health_data, luna Whether to include the record IDs in the response
Method to merge data
select_best_weighted_source, select_highest_coverage_source, select_most_granular_source, select_highest_priority_source_type, merge_maximize_coverage, merge_maximize_granularity, merge_maximize_weighted_coverage, merge_all_samples Device types to include
unknown, phone, watch, scale, ring, head_mounted, fitness_band, chest_strap, smart_display, accessory Response
OK
The metric type for these timeseries
heartrate_max, heartrate_min, heartrate_zone0_duration, heartrate_zone1_duration, heartrate_zone2_duration, heartrate_zone3_duration, heartrate_zone4_duration, heartrate_zone5_duration, heartrate, heartrate_resting, heartrate_resting_min, heartrate_resting_max, hrv_rmssd, hrv_sdnn, elevation_max, elevation_min, elevation_gain, elevation_loss, ascent, descent, calories_burned_active, calories_burned_basal, calories_burned, calories_intake, steps, floors_climbed, distance, distance_walking, distance_cycling, distance_running, distance_wheelchair, distance_swimming, speed, speed_max, speed_min, air_temperature_max, air_temperature, air_temperature_min, spo2, spo2_max, spo2_min, breathing_rate, breathing_rate_min, breathing_rate_max, longitude, latitude, elevation, duration_active, swimming_lengths, swimming_distance_per_stroke, sleep_efficiency, sleep_duration, sleep_duration_deep, sleep_duration_light, sleep_duration_rem, sleep_duration_awake, bedtime_duration, sleep_interruptions, sleep_duration_nap, sleep_score, sleep_breathing_rate, sleep_breathing_rate_min, sleep_breathing_rate_max, sleep_latency, wakeup_latency, cadence, cadence_min, cadence_max, pace, body_mass_index, weight, height, vo2max, body_temperature, body_temperature_max, body_temperature_min, basal_body_temperature, basal_body_temperature_max, basal_body_temperature_min, skin_temperature, skin_temperature_max, skin_temperature_min, sleep_skin_temperature_deviation, ecg_voltage, ecg_rri, body_fat, body_fat_min, body_fat_max, blood_pressure_systolic, blood_pressure_systolic_min, blood_pressure_systolic_max, blood_pressure_diastolic, blood_pressure_diastolic_min, blood_pressure_diastolic_max, body_bone_mass, glucose Device types involved for these timeseries
unknown, phone, watch, scale, ring, head_mounted, fitness_band, chest_strap, smart_display, accessory Duration of each timeseries entry in milliseconds
Millisecond offsets from the start_at timestamp
Provider sources involved for these timeseries
apple_healthkit_sample, apple_healthkit_activity, apple_healthkit_sample_category, apple_healthkit_sleep_aggregation, apple_healthkit_statistics, apple_healthkit_characteristics, apple_healthkit_ecgs, apple_healthkit_mindfulness, health_connect_record, health_connect_activity, health_connect_mindfulness_session, health_connect_aggregation, fitbit_activities_list, fitbit_activities_daily_summary, fitbit_activities_daily_summary_activity, fitbit_activity_heart_intraday, fitbit_activity_steps_intraday, fitbit_activity_distance_intraday, fitbit_activity_calories_intraday, fitbit_hrv_summary, fitbit_hrv_intraday, fitbit_vo2max_summary, fitbit_sleep_summary, fitbit_activity_tcx, fitbit_br_summary, fitbit_br_intraday, fitbit_spo2_summary, fitbit_spo2_intraday, fitbit_core_temperature_summary, fitbit_skin_temperature_summary, fitbit_ecg, fitbit_body_log_fat, fitbit_body_log_weight, garmin_wellness_epochs, garmin_wellness_dailies, garmin_wellness_activities, garmin_wellness_activity_details, garmin_wellness_sleep, garmin_wellness_activity_file, garmin_wellness_hrv, garmin_wellness_user_metrics, garmin_wellness_body_comps, garmin_wellness_blood_pressures, garmin_wellness_stress_details, garmin_wellness_skin_temperature, oura_user_collection_daily_activity_document, oura_user_collection_sleep_document, oura_user_collection_workout_document, oura_user_collection_daily_spo2_document, oura_user_collection_vo2_max, oura_user_collection_hr_document, oura_user_collection_session_document, oura_personal_info, polar_continuous_heart_rate_by_date, polar_exercise, polar_exercise_fit_file, polar_sleep_available, polar_activity_transaction, polar_activity_transaction_steps, polar_sleep_by_date, polar_nightly_recharge, polar_biosensing_spo2, polar_biosensing_body_temperature, polar_biosensing_skin_temperature, polar_physical_information, polar_biosensing_ecg, polar_user_info, strava_activity, suunto_workout_summary, suunto_workout_fit_file, suunto_activity_samples, suunto_activity_daily_summary, suunto_sleep_samples, whoop_cycle, whoop_cycle_recovery, whoop_activity_sleep, whoop_activity_workout, whoop_user_body_measurement, withings_sleep_summary, withings_sleep_get, withings_measure_workouts, withings_measure_activity, withings_measure_meas, withings_measure_activity_intraday, withings_heart_list, withings_heart_get, withings_sleep_combined, wahoo_workout_summary, wahoo_workout_fit_file, huawei_activity_record, huawei_sampling_data_daily_activity_summary, huawei_sampling_data_details, huawei_sampling_data_group_by, huawei_sampling_data_daily, huawei_health_record, huawei_sampling_data_latest, ultrahuman_heartrate_metrics, ultrahuman_hrv_metrics, ultrahuman_temp_metrics, ultrahuman_heartrate_resting_metrics, ultrahuman_steps_metrics, ultrahuman_vo2max_metrics, ultrahuman_glucose_metrics, ultrahuman_sleep_metrics, coros_workout, coros_workout_fit_file, coros_daily_record, coros_daily_record_sleep, samsung_health_data_aggregation, samsung_health_data_data_point_collection, dexcom_egvs, freestyle_libre_glucose, luna_sleep, omron_us_blood_pressure, omron_us_hourly_activity, omron_us_weight, omron_us_temperature, omron_us_oxygen, omron_eu_blood_pressure, omron_eu_hourly_activity, omron_eu_weight, omron_eu_temperature, omron_eu_oxygen, compat_apple_healthkit_entry, compat_health_connect_entry Providers involved for these timeseries
Provider slugs
IDs of the records containing these timeseries
Unique identifier for a record.
The actual metric values for each timeseries entry