Time Series

Read one sampled vital as a dense sequence of fixed-resolution buckets.

6 min read Updated Sep 16, 2026

GET /v1/users/{id}/timeseries

Returns one metric averaged into buckets aligned to the user’s local midnight.

Query parameter	Default	Rules
`metric`	required	One ID from the time-series catalog
`from_date`	`to_date`	Inclusive `YYYY-MM-DD`
`to_date`	current date in the user’s timezone	Inclusive `YYYY-MM-DD`
`resolution`	`5m`	`1m`, `5m`, `15m`, or `1h`

The maximum range is 31 days, or 7 days at 1m resolution. One request returns one metric.

http

GET /v1/users/7e4e91a5-1e4f-4fc2-903c-251046d2a4d3/timeseries?metric=heart_rate&from_date=2026-09-03&to_date=2026-09-03&resolution=15m

The response below is abbreviated: values shows the first six of the 96 buckets returned for this window.

json

{
  "metric": "heart_rate",
  "resolution": "15m",
  "from_date": "2026-09-03",
  "to_date": "2026-09-03",
  "start": "2026-09-03T00:00:00",
  "step_seconds": 900,
  "values": [54.2, 52.8, null, null, 55, 96.1]
}

Bucket i begins at start + i * step_seconds. The values array covers the full requested window, so one day at 15m always contains 96 values. A bucket without readings is null; a populated bucket is the mean of its samples in the metric’s canonical unit.

The timestamps are local wall time

from_date and to_date select calendar days in the timezone saved on the user’s profile. start has no UTC offset and uses that same timezone. If the profile has no timezone, Sonar uses UTC.

The underlying samples remain UTC instants. Sonar converts local midnight to the correct UTC boundary before reading them, then returns the buckets on the user’s wall clock. Do not append Z to start.

Daylight-Saving Transitions

The response keeps a fixed wall-clock grid: one day always contains 1,440 buckets at 1m, 288 at 5m, 96 at 15m, or 24 at 1h.

When clocks move forward, the skipped local hour contains null buckets because those wall times did not occur.
When clocks move backward, both occurrences of the repeated hour map to the same wall-clock buckets and their samples are averaged together.

This preserves a stable chart axis. If an application needs an unambiguous absolute instant for every raw sample, the current bucketed endpoint does not expose that shape.

Daily totals such as steps, distance, and calories are not sampled metrics and return 422 invalid_metric. Read them from GET /daily.