📘 Note
All fields in all models are nullable unless explicitly stated otherwise.
🚧 Uniquely identifying payloads
Activity
Activity payloads can be uniquely identified by their summary_id
field under metadata
. If an activity comes in a second time, with the same summary ID, you should update the previous entries with the new data corresponding to that summary_id
Body, Daily, Sleep, Nutrition
Body, Daily, Sleep, Nutrition payloads can be uniquely identified by the combination of their start_time
and end_time
fields under metadata
. If one of these payloads comes in again, with the same start_time
and end_time
, you should update the previous entries with the new data.
For example, the Daily
payload can come in multiple times in one day, with updated steps
field every time
🚧 Schema parser
When building a parser for the models below, please take into account that more fields may be added down the line (but no field name should ever change within a given version)
Also note that this version is equivalent to 2022_03_16
TerraUser
Copy {
"user_id": String, // not nullable
"provider": String, // not nullable
"last_webhook_update": String,
"scopes": String,
"reference_id": String
}
Core data types
Activity
Copy {
// NOTE ────────────────────────────────────────────────────
// ❶ Unless a property is explicitly documented as
// “required / non‑null”, **it may be `null`.**
// ❷ Date‑time strings are ISO‑8601.
// ❸ Top‑level keys are listed alphabetically for clarity.
// ─────────────────────────────────────────────────────────
"active_durations_data": {
"activity_levels_samples": Array<ActivityLevelSample>,
"activity_seconds": Number,
"inactivity_seconds": Number,
"low_intensity_seconds": Number,
"moderate_intensity_seconds": Number,
"num_continuous_inactive_periods": Number,
"rest_seconds": Number,
"standing_hours_count": Number,
"standing_seconds": Number,
"vigorous_intensity_seconds": Number
},
"calories_data": {
"BMR_calories": Number,
"calorie_samples": Array<CalorieSample>,
"net_activity_calories": Number,
"net_intake_calories": Number,
"total_burned_calories": Number
},
"cheat_detection": CheatDetection,
"data_enrichment": {
"stress_score": Number
},
"device_data": {
"activation_timestamp": String,
"data_provided": Array<DeviceDataType>,
"hardware_version": String,
"last_upload_date": String,
"manufacturer": String,
"name": String,
"other_devices": Array<OtherDeviceData>,
"serial_number": String,
"software_version": String
},
/* schema for each element of other_devices */
"OtherDeviceData": {
"activation_timestamp": String,
"data_provided": Array<DeviceDataType>,
"hardware_version": String,
"last_upload_date": String,
"manufacturer": String,
"name": String,
"serial_number": String,
"software_version": String
},
"distance_data": {
"detailed": {
"distance_samples": Array<DistanceSample>,
"elevation_samples": Array<ElevationSample>,
"floors_climbed_samples": Array<FloorsClimbedSample>,
"step_samples": Array<StepSample>
},
"summary": {
"distance_meters": Number,
"elevation": {
"avg_meters": Number,
"gain_actual_meters": Number,
"gain_planned_meters": Number,
"loss_actual_meters": Number,
"max_meters": Number,
"min_meters": Number
},
"floors_climbed": Number,
"steps": Number,
"swimming": {
"num_laps": Number,
"num_strokes": Number,
"pool_length_meters": Number
}
}
},
"energy_data": {
"energy_kilojoules": Number,
"energy_planned_kilojoules": Number
},
"heart_rate_data": {
"detailed": {
"hr_samples": Array<HeartRateDataSample>,
"hrv_samples_rmssd": Array<HeartRateVariabilityDataSampleRMSSD>,
"hrv_samples_sdnn": Array<HeartRateVariabilityDataSampleSDNN>
},
"summary": {
"avg_hr_bpm": Number,
"avg_hrv_rmssd": Number,
"avg_hrv_sdnn": Number,
"hr_zone_data": Array<HeartRateZoneData>,
"max_hr_bpm": Number,
"min_hr_bpm": Number,
"resting_hr_bpm": Number,
"user_max_hr_bpm": Number
}
},
"lap_data": {
"laps": Array<LapSample>
},
"MET_data": {
"MET_samples": Array<METSample>,
"avg_level": Number,
"num_high_intensity_minutes": Number,
"num_inactive_minutes": Number,
"num_low_intensity_minutes": Number,
"num_moderate_intensity_minutes": Number
},
"metadata": {
"city": String,
"country": String,
"end_time": String, // required
"name": String,
"start_time": String, // required
"state": String,
"summary_id": String, // required
"timestamp_localization": Number,
"type": ActivityType, // required
"upload_type": UploadType // required
},
"movement_data": {
"adjusted_max_speed_meters_per_second": Number,
"avg_cadence_rpm": Number,
"avg_pace_minutes_per_kilometer": Number,
"avg_speed_meters_per_second": Number,
"avg_torque_newton_meters": Number,
"avg_velocity_meters_per_second": Number,
"cadence_samples": Array<CadenceSample>,
"max_cadence_rpm": Number,
"max_pace_minutes_per_kilometer": Number,
"max_speed_meters_per_second": Number,
"max_torque_newton_meters": Number,
"max_velocity_meters_per_second": Number,
"normalized_speed_meters_per_second": Number,
"speed_samples": Array<SpeedSample>,
"torque_samples": Array<TorqueSample>
},
"oxygen_data": {
"avg_saturation_percentage": Number,
"saturation_samples": Array<OxygenSaturationSample>,
"vo2_samples": Array<Vo2MaxSample>,
"vo2max_ml_per_min_per_kg": Number
},
"polyline_map_data": {
"summary_polyline": String
},
"position_data": {
"center_pos_lat_lng_deg": [Number, Number],
"end_pos_lat_lng_deg": [Number, Number],
"position_samples": Array<PositionSample>,
"start_pos_lat_lng_deg": [Number, Number]
},
"power_data": {
"avg_watts": Number,
"max_watts": Number,
"power_samples": Array<PowerSample>
},
"strain_data": {
"strain_level": Number
},
"TSS_data": {
"TSS_samples": Array<TSSSample>
},
"work_data": {
"work_kilojoules": Number
}
}
Athlete
Copy {
"age": Number,
"country": String,
"bio": String,
"state": String,
"last_name": String,
"sex": String,
"city": String,
"email": String,
"date_of_birth": String,
"first_name": String,
"gender": String,
"joined_provider": String,
"devices": Array<device_data>
}
Body
Copy {
"blood_pressure_data": {
"blood_pressure_samples": Array<BloodPressureSample>
},
"device_data": {
"activation_timestamp": String,
"data_provided": Array<DeviceDataType>,
"hardware_version": String,
"last_upload_date": String,
"manufacturer": String,
"name": String,
"other_devices": Array<OtherDeviceData>,
"sensor_state": String,
"serial_number": String,
"software_version": String
},
"heart_data": {
"afib_classification_samples": Array<AFibClassificationSample>,
"ecg_signal": Array<ECGReading>,
"heart_rate_data": {
"detailed": {
"hr_samples": Array<HeartRateDataSample>,
"hrv_samples_rmssd": Array<HeartRateVariabilityDataSampleRMSSD>,
"hrv_samples_sdnn": Array<HeartRateVariabilityDataSampleSDNN>
},
"summary": {
"avg_hr_bpm": Number,
"avg_hrv_rmssd": Number,
"avg_hrv_sdnn": Number,
"hr_zone_data": Array<HeartRateZoneData>,
"max_hr_bpm": Number,
"min_hr_bpm": Number,
"resting_hr_bpm": Number,
"user_max_hr_bpm": Number
}
},
"pulse_wave_velocity_samples": Array<PulseVelocitySample>,
"rr_interval_samples": Array<RRInterval>
},
"hydration_data": {
"day_total_water_consumption_ml": Number,
"hydration_amount_samples": Array<HydrationLevelSample>,
"hydration_level_samples": Array<HydrationMeasurementSample>
},
"ketone_data": {
"ketone_samples": Array<KetoneSample>
},
"measurements_data": {
"measurements": Array<MeasurementDataSample>
},
"metadata": {
"end_time": String, // required
"start_time": String // required
},
"oxygen_data": {
"avg_saturation_percentage": Number,
"saturation_samples": Array<OxygenSaturationSample>,
"vo2_samples": Array<Vo2MaxSample>,
"vo2max_ml_per_min_per_kg": Number
},
"temperature_data": {
"ambient_temperature_samples": Array<TemperatureSample>,
"body_temperature_samples": Array<TemperatureSample>,
"skin_temperature_samples": Array<TemperatureSample>,
"day_avg_blood_glucose_mg_per_dL": Number,
"daily_patterns": Array<DailyPatternSample>,
"detailed_blood_glucose_samples": Array<GlucoseDataSample>,
"gmi": Number,
"sensor_usage": Number,
"time_in_range": Number
}
}
Daily
Copy {
"active_durations_data": {
"activity_levels_samples": Array<ActivityLevelSample>,
"activity_seconds": Number,
"inactivity_seconds": Number,
"low_intensity_seconds": Number,
"moderate_intensity_seconds": Number,
"num_continuous_inactive_periods": Number,
"rest_seconds": Number,
"standing_hours_count": Number,
"standing_seconds": Number,
"vigorous_intensity_seconds": Number
},
"calories_data": {
"BMR_calories": Number,
"calorie_samples": Array<CalorieSample>,
"net_activity_calories": Number,
"net_intake_calories": Number,
"total_burned_calories": Number
},
"data_enrichment": {
"cardiovascular_contributors": Array<DataContributor>,
"cardiovascular_score": Number,
"immune_contributors": Array<DataContributor>,
"immune_index": Number,
"readiness_contributors": Array<DataContributor>,
"readiness_score": Number,
"respiratory_contributors": Array<DataContributor>,
"respiratory_score": Number,
"start_time": String,
"stress_contributors": Array<DataContributor>,
"total_stress_score": Number
},
"device_data": {
"activation_timestamp": String,
"data_provided": Array<DeviceDataType>,
"hardware_version": String,
"last_upload_date": String,
"manufacturer": String,
"name": String,
"other_devices": Array<OtherDeviceData>,
"serial_number": String,
"software_version": String
},
"distance_data": {
"detailed": {
"distance_samples": Array<DistanceSample>,
"elevation_samples": Array<ElevationSample>,
"floors_climbed_samples": Array<FloorsClimbedSample>,
"step_samples": Array<StepSample>
},
"distance_meters": Number,
"elevation": {
"avg_meters": Number,
"gain_actual_meters": Number,
"gain_planned_meters": Number,
"loss_actual_meters": Number,
"max_meters": Number,
"min_meters": Number
},
"floors_climbed": Number,
"steps": Number,
"swimming": {
"num_laps": Number,
"num_strokes": Number,
"pool_length_meters": Number
}
},
"heart_rate_data": {
"detailed": {
"hr_samples": Array<HeartRateDataSample>,
"hrv_samples_rmssd": Array<HeartRateVariabilityDataSampleRMSSD>,
"hrv_samples_sdnn": Array<HeartRateVariabilityDataSampleSDNN>
},
"summary": {
"avg_hr_bpm": Number,
"avg_hrv_rmssd": Number,
"avg_hrv_sdnn": Number,
"hr_zone_data": Array<HeartRateZoneData>,
"max_hr_bpm": Number,
"min_hr_bpm": Number,
"resting_hr_bpm": Number,
"user_max_hr_bpm": Number
}
},
"MET_data": {
"MET_samples": Array<METSample>,
"avg_level": Number,
"num_high_intensity_minutes": Number,
"num_inactive_minutes": Number,
"num_low_intensity_minutes": Number,
"num_moderate_intensity_minutes": Number
},
"metadata": {
"end_time": String, // required
"start_time": String, // required
"timestamp_localization": Number,
"upload_type": UploadType // required
},
"oxygen_data": {
"avg_saturation_percentage": Number,
"saturation_samples": Array<OxygenSaturationSample>,
"vo2_samples": Array<Vo2MaxSample>,
"vo2max_ml_per_min_per_kg": Number
},
"scores": {
"activity": Number,
"recovery": Number,
"sleep": Number
},
"strain_data": {
"strain_level": Number
},
"stress_data": {
"activity_stress_duration_seconds": Number,
"avg_stress_level": Number,
"body_battery_samples": Array<BodyBatterySample>,
"high_stress_duration_seconds": Number,
"low_stress_duration_seconds": Number,
"max_stress_level": Number,
"medium_stress_duration_seconds": Number,
"rest_stress_duration_seconds": Number,
"samples": Array<StressSample>,
"stress_duration_seconds": Number,
"stress_rating": Number
},
"tag_data": {
"tags": Array<TagEntry>
}
}
Menstruation
Copy {
"metadata": {
"end_time": String,
"start_time": String
},
"menstruation_data": {
"period_length_days": Number,
"current_phase": MenstruationFlow,
"length_of_current_phase_days": Number,
"days_until_next_phase": Number,
"period_start_date": String,
"predicted_cycle_length_days": Number,
"day_in_cycle": Number,
"last_updated_time": String,
"cycle_length_days": Number,
"is_predicted_cycle": String,
"menstruation_flow": Array<MenstruationFlow>
}
}
Nutrition
Copy {
"drink_samples": Array<DrinkSample>,
"meals": Array<Meal>,
"metadata": {
"end_time": String, // required – ISO‑8601
"start_time": String, // required – ISO‑8601
"timestamp_localization": Number
},
"summary": {
"macros": {
"alcohol_g": Number,
"calories": Number,
"carbohydrates_g": Number,
"cholesterol_mg": Number,
"fat_g": Number,
"fiber_g": Number,
"net_carbohydrates_g": Number,
"protein_g": Number,
"saturated_fat_g": Number,
"sodium_mg": Number,
"sugar_g": Number,
"trans_fat_g": Number
},
"micros": {
"biotin_mg": Number,
"caffeine_mg": Number,
"calcium_mg": Number,
"chloride_mg": Number,
"chromium_mg": Number,
"copper_mg": Number,
"folate_mg": Number,
"folic_acid_mg": Number,
"iodine_mg": Number,
"iron_mg": Number,
"magnesium_mg": Number,
"manganese_mg": Number,
"molybdenum_mg": Number,
"niacin_mg": Number,
"pantothenic_acid_mg": Number,
"phosphorus_mg": Number,
"potassium_mg": Number,
"riboflavin_mg": Number,
"selenium_mg": Number,
"thiamin_mg": Number,
"vitamin_A_mg": Number,
"vitamin_B12_mg": Number,
"vitamin_B6_mg": Number,
"vitamin_C_mg": Number,
"vitamin_D_mg": Number,
"vitamin_D2_mg": Number,
"vitamin_D3_mg": Number,
"vitamin_E_mg": Number,
"vitamin_K_mg": Number,
"zinc_mg": Number,
/* amino‑acids & related */
"cystine_g": Number,
"histidine_g": Number,
"isoleucine_g": Number,
"leucine_g": Number,
"lysine_g": Number,
"methionine_g": Number,
"phenylalanine_g": Number,
"threonine_g": Number,
"tryptophan_g": Number,
"tyrosine_g": Number,
"valine_g": Number,
/* fats & fatty‑acids */
"monounsaturated_fat_g": Number,
"polyunsaturated_fat_g": Number,
"omega3_g": Number,
"omega6_g": Number,
/* carbohydrates */
"starch_g": Number
},
"water_ml": Number,
"drink_ml": Number
}
}
Sleep
Copy {
"data_enrichment": {
"sleep_contributors": Array<DataContributor>,
"sleep_score": Number
},
"device_data": {
"activation_timestamp": String,
"data_provided": Array<DeviceDataType>,
"hardware_version": String,
"last_upload_date": String,
"manufacturer": String,
"name": String,
"other_devices": Array<OtherDeviceData>,
"serial_number": String,
"software_version": String
},
"heart_rate_data": {
"detailed": {
"hr_samples": Array<HeartRateDataSample>,
"hrv_samples_rmssd": Array<HeartRateVariabilityDataSampleRMSSD>,
"hrv_samples_sdnn": Array<HeartRateVariabilityDataSampleSDNN>
},
"summary": {
"avg_hr_bpm": Number,
"avg_hrv_rmssd": Number,
"avg_hrv_sdnn": Number,
"hr_zone_data": Array<HeartRateZoneData>,
"max_hr_bpm": Number,
"min_hr_bpm": Number,
"resting_hr_bpm": Number,
"user_max_hr_bpm": Number
}
},
"metadata": {
"end_time": String, // required – ISO‑8601
"start_time": String, // required – ISO‑8601
"is_nap": Boolean,
"summary_id": String,
"timestamp_localization": Number,
"upload_type": SleepUploadType // required
},
"readiness_data": {
"readiness": Number,
"recovery_level": RecoveryLevel
},
"respiration_data": {
"breaths_data": {
"avg_breaths_per_min": Number,
"end_time": String,
"max_breaths_per_min": Number,
"min_breaths_per_min": Number,
"on_demand_reading": Boolean,
"samples": Array<BreathSample>,
"start_time": String
},
"oxygen_saturation_data": {
"avg_saturation_percentage": Number,
"end_time": String,
"samples": Array<OxygenSaturationSample>,
"start_time": String
},
"snoring_data": {
"end_time": String,
"num_snoring_events": Number,
"samples": Array<SnoringSample>,
"start_time": String,
"total_snoring_duration_seconds": Number
}
},
"scores": {
"sleep": Number
},
"sleep_durations_data": {
"asleep": {
"duration_asleep_state_seconds": Number,
"duration_deep_sleep_state_seconds": Number,
"duration_light_sleep_state_seconds": Number,
"duration_REM_sleep_state_seconds": Number,
"num_REM_events": Number
},
"awake": {
"duration_awake_state_seconds": Number,
"duration_long_interruption_seconds": Number,
"duration_short_interruption_seconds": Number,
"num_out_of_bed_events": Number,
"num_wakeup_events": Number,
"sleep_latency_seconds": Number,
"wake_up_latency_seconds": Number
},
"hypnogram_samples": Array<SleepHypnogramSample>,
"other": {
"duration_in_bed_seconds": Number,
"duration_unmeasurable_sleep_seconds": Number
},
"sleep_efficiency": Number
},
"temperature_data": {
"delta": Number
}
}
Enums
DeviceDataType
Represents data types that a certain device contributed to
Sleep type classification
AFibFlag
Negative (AFib not present)
ActivityType
ActivityLevel
HeartRateZone
Other/custom classification
SleepLevel
UploadType
SleepUploadType
StrokeType
GlucoseFlag
NutritionUnits
RecoveryLevel
TrendArrow
MenstruationFlow
MealType
StressLevel
HeartRateContext
MenstrualPhase
PlannedWorkout
Copy {
"steps": Array<PlannedWorkoutStep||PlannedWorkoutRepeatStep>,
"metadata": {
"id": String,
"estimated_if": Number,
"provider": String,
"estimated_distance_meters": Number,
"estimated_elevation_gain_meters": Number,
"estimated_energy_kj": Number,
"estimated_speed_meters_per_second": Number,
"planned_date": ISO-Date-String,
"created_date": ISO-Date-String,
"estimated_tss": Number,
"type": WorkoutTypeNumber,
"name": String,
"description": String,
"pool_length_meters": Number,
"estimated_calories": Number,
"estimated_duration_seconds": Number
}
}
PlannedWorkoutStep
Copy {
"description": String,
"order": Number,
"intensity": Number,
"durations": Array<PlannedWorkoutStepDuration>
"type": 0,
"targets": Array<PlannedWorkoutStepTarget>,
"stroke_type": Number, //for Swimming Workouts
"equipement_type": Number, //for Swimming Workouts
"exercice_category" : Number, //for Strength and Cardio workouts
"exercice_name": String, //for Strength and Cardio workouts
"weight_kg": Number, //for Strength workouts
}
Step Intensity Name
Step Intensity Number Value
PlannedWorkoutRepeatStep
Copy {
"description": String,
"order": Number,
"intensity": Number,
"durations": Array<PlannedWorkoutStepDuration>
"type": 1,
"targets": Array<PlannedWorkoutStepTarget>,
"steps" : Array<PlannedWorkoutStep>
}
PlannedWorkoutStepTarget
{ "target_type": 0, "speed_meters_per_second": Number, "speed_meters_per_second_low": Number, "speed_meters_per_second_high": Number }
{ "target_type": 1, "hr_bpm_high": Number, "hr_bpm_low": Number }
{ "target_type": 3, "cadence": Number, "cadence_high": Number, "cadence_low" : Number }
{ "target_type": 4, "power_watt_high": Number, "power_watt_low": Number, "power_watt": Number }
{ "target_type": 8, "swim_strokes": Number }
{ "target_type": 11, "speed_meters_per_second": Number, "speed_meters_per_second_low": Number, "speed_meters_per_second_high": Number }
HEART_RATE_THRESHOLD_PERCENTAGE
{ "target_type": 12, "hr_percentage": Number, "hr_percentage_low": Number, "hr_percentage_high": Number }
HEART_RATE_MAX_PERCENTAGE
{ "target_type": 13, "hr_percentage": Number, "hr_percentage_low": Number, "hr_percentage_high": Number }
{ "target_type": 14, "speed_percentage": Number, "speed_percentage_low": Number, "speed_percentage_high": Number }
{ "target_type": 15, "power_percentage": Number, "power_percentage_low": Number, "power_percentage_high": Number }
{ "target_type": 16, "repetitions": Number }
PlannedWorkoutStepDuration
{ "duration_type": 0, "seconds": Number }
{ "duration_type": 1, "distance_meters": Number }
{ "duration_type": 2, "hr_below_bpm": Number }
{ "duration_type": 3, "hr_above_bpm": Number }
{ "duration_type": 4, "calories": 2.0 }
{ "duration_type": 6, "power_below_watts": Number }
{ "duration_type": 7, "power_above_watts": Number }
{ "duration_type": 9, "reps": Number }
{ "duration_type": 10, "rest_seconds": Number }
{ "duration_type": 12, "steps": Number }
Enums