---
title: "Get Samples Time Series"
method: GET
path: "/queries/timeseries/samples"
tags: ["Queries / Time Series"]
---

# Get Samples Time Series

`GET /queries/timeseries/samples`

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

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

## Response Example

```json
{
  "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>

## Query parameters

- `from_timestamp` string, date-time — Start time of the query range in UTC, inclusive
- `to_timestamp` string, date-time — 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
- `providers` string[]
- `include_record_ids` boolean — Whether to include the record IDs in the response

## Response `200`

OK

- TimeseriesMergedQueryOutput
  - `device_types` string[] — Device types involved for these timeseries
  - `durations` integer[], nullable — Duration of each timeseries entry in milliseconds
  - `from_timestamp` string, 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
  - `offsets` integer[], nullable — Millisecond offsets from the start_at timestamp
  - `provider_sources` string[] — Provider sources involved for these timeseries
  - `providers` string[] — Providers involved for these timeseries
  - `record_ids` string[], nullable — IDs of the records containing these timeseries
  - `to_timestamp` string, date-time
  - `values` MetricValue[], nullable — The actual metric values for each timeseries entry

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `422` — Unprocessable Entity
- `500` — Internal Server Error

---

[API](https://skmtc.dev/spikeapi/apis/application-user-api.md) · [All operations](https://skmtc.dev/spikeapi/apis/application-user-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/spikeapi/application-user-api/revisions/637338fb0c9d/schema)