query_metrics
Fetch health data for specific metrics by name. Metric names are provider-specific and follow each provider's own field-name conventions (e.g. activity_* / wellness_* for Intervals.icu, polar_* for Polar, workout_* for Hevy, sleep_summary_* for Withings). They are NOT common English words. Always call list_metrics first in a session to discover the exact names available for this user — names that aren't in that list return zero rows. Returns scalar values grouped by date. The window is ONE contiguous range (days, or start+end), so to compare specific non-adjacent dates make one call per date with start and end both set to that date — a single wide range spanning them returns newest-first and can truncate the older date away, which is not the same as that date having no data. When include_raw is true, also returns the full JSON payload for each record (per-exercise sets, hypnograms, intra-day sample arrays). Non-sample raw is capped at 50 records per request. For intra-workout sample metrics (names ending in _samples), include_raw returns a downsampled overview by default (tighter record cap — narrow the range if asked to); pass raw_resolution: "full" for every sample of a single workout, or sample_window: { from_sec, to_sec } to zoom a segment of a long workout at full resolution. Each sample row shows 'id: <…>' — pass that as source_id to select one of several same-day workouts for a full or windowed read. When you present Garmin data to the user, attribute it as "Garmin [device model]" (or just "Garmin" when no device is shown), per Garmin's brand requirements.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | End date (inclusive) as YYYY-MM-DD. Defaults to today. Only used when `start` is set. | |
| days | No | Number of days to look back (default: 7, max: 365). For ranges beyond 1 year, use `start` and `end` instead. | |
| range | No | With granularity: also return, per bucket, the share of readings below, inside and above this range (bounds inclusive), computed by freddy at the time of the call and not stored. Pass the range the user gives as their own target, in the metric's unit as list_metrics shows it; if the user has not given one, ask. The range applies only to rows in that unit. | |
| start | No | Start date (inclusive) as YYYY-MM-DD. When set, overrides `days`. Pair with `end` to bound the window. Useful for historical questions ('how was my training in Q1 2024') and for ranges longer than 1 year. | |
| device | No | Filter to a single source device. Device identifiers and per-device record counts are shown by list_metrics. Omit to return all devices. Also useful to reduce result volume for multi-device providers. | |
| metrics | Yes | Metric names to fetch (e.g. ['sleep_duration', 'hrv', 'steps']). For an Apple Health or Health Connect daily total prefer the `<metric>_total` twin (device "Merged") over the per-app rows of the bare metric. | |
| source_id | No | Select ONE specific workout/record by its source id (shown in sample results as 'id: <…>'). This is how you pick one of several same-day workouts for a full-resolution or windowed sample read — date filters alone can't disambiguate two workouts on the same day. | |
| granularity | No | Return one figure per local day, week (Monday start) or calendar month instead of individual rows: avg/min/max/sum/count per metric, computed by freddy from the stored readings at the time of the call and not stored. Use "day" for a daily figure of a per-reading metric (glucose, SpO2, heart rate), and "week" or "month" for multi-month or multi-year questions. Cannot be combined with include_raw. | |
| include_raw | No | Include the full raw JSON payload for each record (per-exercise sets for workouts, per-stage hypnogram for sleep, per-sample arrays for continuous HR). Off by default. Raw payloads can be 5 to 30 KB each, so prefer narrower windows when enabling this. | |
| sample_window | No | For sample metrics with include_raw: return full-resolution samples only for the [from_sec, to_sec] window (seconds from workout start). Use to inspect a segment of a long workout at full fidelity. | |
| raw_resolution | No | For intra-workout sample metrics (names ending in _samples) with include_raw: 'overview' (default) returns a peak-preserving downsample (~240 points/stream) — best for 'how did my heart rate change through the session'. 'full' returns every sample but is capped to ONE workout; for a long workout use sample_window to zoom a segment. |