Skip to main content
Time series endpoints provide access to granular, time-stamped data points for various health metrics. This includes biometrics (heart rate, HRV, SpO2) and activity metrics (steps, energy, distance).

​
Get Time Series Data

​
user_id
string
required
UUID of the user
​
start_time
string
required
Start time for the range (ISO 8601 format or Unix timestamp)
​
end_time
string
required
End time for the range (ISO 8601 format or Unix timestamp)
​
types
array
Array of series types to retrieve. If not specified, returns all available types. See Available Series Types below.
​
resolution
string
default:"raw"
Data resolution for the query. Options:
  • raw - Original sampling resolution from the device
  • 1min - One-minute aggregates
  • 5min - Five-minute aggregates
  • 15min - Fifteen-minute aggregates
  • 1hour - One-hour aggregates
​
cursor
string
Pagination cursor from previous response
​
limit
integer
default:"50"
Number of samples per page (1-100)
cURL
curl -X GET "https://api.openwearables.com/api/v1/users/123e4567-e89b-12d3-a456-426614174000/timeseries?start_time=2024-03-01T00:00:00Z&end_time=2024-03-01T23:59:59Z&types=heart_rate&types=steps&resolution=raw&limit=100" \
  -H "X-API-Key: your_api_key"

​
Response

​
data
array
Array of time series sample objects
​
pagination
object
​
metadata
object
{
  "data": [
    {
      "timestamp": "2024-03-01T08:15:30Z",
      "type": "heart_rate",
      "value": 72,
      "unit": "bpm",
      "source": {
        "provider": "apple_health",
        "device": "Apple Watch Series 9"
      }
    },
    {
      "timestamp": "2024-03-01T08:15:30Z",
      "type": "steps",
      "value": 45,
      "unit": "count",
      "source": {
        "provider": "apple_health",
        "device": "iPhone 15 Pro"
      }
    },
    {
      "timestamp": "2024-03-01T08:16:45Z",
      "type": "heart_rate",
      "value": 75,
      "unit": "bpm",
      "source": {
        "provider": "apple_health",
        "device": "Apple Watch Series 9"
      }
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6IjEyMzQ1Njc4OTAiLCJ0cyI6MTcwNDA2NzIwMH0",
    "previous_cursor": null,
    "has_more": true,
    "total_count": 1548
  },
  "metadata": {
    "resolution": "raw",
    "sample_count": 3,
    "start_time": "2024-03-01T00:00:00Z",
    "end_time": "2024-03-01T23:59:59Z"
  }
}

​
Available Series Types

The following series types are supported in the types query parameter:

​
Heart & Cardiovascular

  • heart_rate - Heart rate (bpm)
  • resting_heart_rate - Resting heart rate (bpm)
  • heart_rate_variability_sdnn - HRV SDNN (ms)
  • heart_rate_variability_rmssd - HRV RMSSD (ms)
  • heart_rate_recovery_one_minute - HR recovery after 1 minute (bpm)
  • walking_heart_rate_average - Average heart rate during walking (bpm)
  • recovery_score - Recovery score (0-100)

​
Blood & Respiratory

  • oxygen_saturation - SpO2 (percent)
  • blood_glucose - Blood glucose (mg/dL)
  • blood_pressure_systolic - Systolic blood pressure (mmHg)
  • blood_pressure_diastolic - Diastolic blood pressure (mmHg)
  • respiratory_rate - Respiratory rate (breaths per minute)
  • sleeping_breathing_disturbances - Breathing disturbances during sleep (count)
  • blood_alcohol_content - Blood alcohol content (mg/dL)
  • peripheral_perfusion_index - Perfusion index (score)
  • forced_vital_capacity - FVC (liters)
  • forced_expiratory_volume_1 - FEV1 (liters)
  • peak_expiratory_flow_rate - Peak expiratory flow (liters)

​
Body Composition

  • height - Height (cm)
  • weight - Weight (kg)
  • body_fat_percentage - Body fat (percent)
  • body_mass_index - BMI (kg/m²)
  • lean_body_mass - Lean body mass (kg)
  • body_temperature - Body temperature (celsius)
  • skin_temperature - Skin temperature (celsius)
  • waist_circumference - Waist circumference (cm)
  • body_fat_mass - Body fat mass (kg)
  • skeletal_muscle_mass - Skeletal muscle mass (kg)

​
Fitness Metrics

  • vo2_max - VO2 Max (ml/kg/min)
  • six_minute_walk_test_distance - 6-minute walk test distance (meters)

​
Activity - Basic

  • steps - Step count (count)
  • energy - Active energy burned (kcal)
  • basal_energy - Basal energy burned (kcal)
  • stand_time - Standing time (minutes)
  • exercise_time - Exercise time (minutes)
  • physical_effort - Physical effort score (score)
  • flights_climbed - Flights of stairs climbed (count)
  • average_met - Average metabolic equivalent (MET)

​
Activity - Distance

  • distance_walking_running - Walking/running distance (meters)
  • distance_cycling - Cycling distance (meters)
  • distance_swimming - Swimming distance (meters)
  • distance_downhill_snow_sports - Downhill skiing/snowboarding distance (meters)
  • distance_other - Other activity distance (meters)

​
Activity - Walking Metrics

  • walking_step_length - Step length (cm)
  • walking_speed - Walking speed (m/s)
  • walking_double_support_percentage - Double support time (percent)
  • walking_asymmetry_percentage - Gait asymmetry (percent)
  • walking_steadiness - Walking steadiness (percent)
  • stair_descent_speed - Stair descent speed (m/s)
  • stair_ascent_speed - Stair ascent speed (m/s)

​
Activity - Running Metrics

  • running_power - Running power (watts)
  • running_speed - Running speed (m/s)
  • running_vertical_oscillation - Vertical oscillation (cm)
  • running_ground_contact_time - Ground contact time (ms)
  • running_stride_length - Stride length (cm)

​
Activity - Swimming Metrics

  • swimming_stroke_count - Swimming strokes (count)
  • underwater_depth - Underwater depth (meters)

​
Activity - Generic

  • cadence - Cadence (rpm)
  • power - Power output (watts)
  • speed - Speed (m/s)
  • workout_effort_score - Workout effort score (score)
  • estimated_workout_effort_score - Estimated workout effort (score)

​
Environmental

  • environmental_audio_exposure - Environmental audio exposure (dB)
  • headphone_audio_exposure - Headphone audio exposure (dB)
  • environmental_sound_reduction - Sound reduction (dB)
  • time_in_daylight - Time in daylight (minutes)
  • water_temperature - Water temperature (celsius)
  • uv_exposure - UV exposure (count)
  • inhaler_usage - Inhaler usage (count)
  • weather_temperature - Weather temperature (celsius)
  • weather_humidity - Weather humidity (percent)

​
Provider-Specific Metrics

Garmin:
  • garmin_stress_level - Garmin stress level (score 1-100)
  • garmin_skin_temperature - Skin temperature deviation from baseline (celsius)
  • garmin_fitness_age - Garmin fitness age estimate (years)
  • garmin_body_battery - Garmin body battery (percent 0-100)

​
Other Metrics

  • electrodermal_activity - Electrodermal activity (count)
  • push_count - Push count for wheelchair users (count)
  • atrial_fibrillation_burden - AFib burden (count)
  • insulin_delivery - Insulin delivery (count)
  • number_of_times_fallen - Falls (count)
  • number_of_alcoholic_beverages - Alcoholic beverages consumed (count)
  • nike_fuel - Nike Fuel points (count)
  • hydration - Water intake (mL)

​
Usage Examples

​
Query Multiple Metrics

curl -X GET "https://api.openwearables.com/api/v1/users/123e4567-e89b-12d3-a456-426614174000/timeseries?start_time=2024-03-01T00:00:00Z&end_time=2024-03-01T12:00:00Z&types=heart_rate&types=oxygen_saturation&types=respiratory_rate" \
  -H "X-API-Key: your_api_key"

​
Query with Aggregation

curl -X GET "https://api.openwearables.com/api/v1/users/123e4567-e89b-12d3-a456-426614174000/timeseries?start_time=2024-03-01T00:00:00Z&end_time=2024-03-07T23:59:59Z&types=steps&resolution=1hour" \
  -H "X-API-Key: your_api_key"

​
Paginate Through Results

# First request
curl -X GET "https://api.openwearables.com/api/v1/users/123e4567-e89b-12d3-a456-426614174000/timeseries?start_time=2024-03-01T00:00:00Z&end_time=2024-03-01T23:59:59Z&types=heart_rate&limit=100" \
  -H "X-API-Key: your_api_key"

# Next page using cursor from previous response
curl -X GET "https://api.openwearables.com/api/v1/users/123e4567-e89b-12d3-a456-426614174000/timeseries?start_time=2024-03-01T00:00:00Z&end_time=2024-03-01T23:59:59Z&types=heart_rate&limit=100&cursor=eyJpZCI6IjEyMzQ1Njc4OTAiLCJ0cyI6MTcwNDA2NzIwMH0" \
  -H "X-API-Key: your_api_key"

Build docs developers (and LLMs) love

Get started for freeTalk to us