Sign in

v1

latestOpenAPI 3.1.02026-07-136587849.3 KB
Queries / Time Series

Get Samples Time Series

This endpoint returns only sample data points (individual measurements) from time series data, excluding any aggregated data. Uses the merge_all_samples merge method to combine data from multiple sources while preserving individual sample points.

<Note> The arrays `offsets`, `durations`, and `values` will all be of the same length. This alignment is crucial for interpreting the data correctly. </Note>

Data Filtering

This endpoint returns only sample data points, meaning:

  • Individual measurements with zero duration (instantaneous readings)
  • No aggregated data (daily summaries, hourly averages, etc.)
  • Data is merged from all available sources using the merge_all_samples method

Request Example

{
  "from_timestamp": "2024-01-01T00:00:00Z",
  "to_timestamp": "2024-01-02T00:00:00Z",
  "metric": "heartrate",
  "include_record_ids": true
}

Response Example

{
  "metric": "heartrate",
  "start_at": "2024-01-01T00:00:00Z",
  "offsets": [0, 60000, 120000],
  "values": [100, 150, 200],
  "record_ids": ["ff000000-0000-0000-0000-000000000000"],
  "providers": ["apple"],
  "provider_sources": ["apple_healthkit_sample"]
}
<Note> For sample data, the `durations` field is omitted from the response since all sample points have zero duration. </Note>
get/queries/timeseries/samples

Query parameters

from_timestampstring date-time

Start time of the query range in UTC, inclusive

Example:2006-01-02T15:04:05

Start time of the query range in UTC, inclusive

to_timestampstring date-time

End time of the query range in UTC, non-inclusive

Example:2006-01-02T15:04:05

End time of the query range in UTC, non-inclusive

metric'heartrate' | 'heartrate_resting' | 'hrv_rmssd' | 'hrv_sdnn' | 'floors_climbed' | 'speed' | 'air_temperature' | 'spo2' | 'breathing_rate' | 'elevation' | 'sleep_breathing_rate' | 'cadence' | 'body_mass_index' | 'weight' | 'height' | 'vo2max' | 'body_temperature' | 'basal_body_temperature' | 'skin_temperature' | 'body_fat' | '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' | 'power' | 'power_max' | 'duration_low_intensity' | 'duration_moderate_intensity' | 'duration_high_intensity' required

The metric you want to query

The metric you want to query

providersstring[]
include_record_idsboolean

Whether to include the record IDs in the response

Whether to include the record IDs in the response

Response

OK

device_typesstring[]

Device types involved for these timeseries

durationsinteger[] nullable

Duration of each timeseries entry in milliseconds

from_timestampstring date-time
metric'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' | 'power' | 'power_max' | 'duration_low_intensity' | 'duration_moderate_intensity' | 'duration_high_intensity' required

The metric type for these timeseries

offsetsinteger[] nullable

Millisecond offsets from the start_at timestamp

provider_sourcesstring[]

Provider sources involved for these timeseries

providersstring[]

Providers involved for these timeseries

record_idsstring[] nullable

IDs of the records containing these timeseries

to_timestampstring date-time
valuesMetricValue[] nullable

The actual metric values for each timeseries entry

Example response

{
  "from_timestamp": "2006-01-02T00:00:00Z",
  "providers": [
    "strava"
  ],
  "record_ids": [
    "12345678-1234-abcd-4321-abcdef123456"
  ],
  "to_timestamp": "2006-01-02T00:00:00Z"
}