Timeseries — API Reference

Intraday samples — heart rate, HRV, stress, blood oxygen, steps, active calories.

GET /users/{user_id}/timeseries Get timeseries data

Returns intraday samples for supported metrics. Resolution varies by device (1-second to 15-minute samples). Query in windows of 7 days or less for best performance.

Parameter	In	Type	Required	Description
`user_id`	path	`string`	required	Sonar user ID
`metrics`	query	`string`	required	Comma-separated metric IDs. Supported: `heart_rate`, `heart_rate_variability`, `stress_score`, `blood_oxygen`, `steps`, `active_calories`
`start_date`	query	`string (date)`	required	Start date (ISO 8601)
`end_date`	query	`string (date)`	required	End date (ISO 8601). Recommended max: 7 days.
`unit_system`	query	`string`	optional	`metric` (default) or `imperial`
`include_sources`	query	`boolean`	optional	Include which device contributed each sample (default: false)

Example Request

bash

curl -X GET \
  "https://api.sonarhealth.co/v1/users/:user_id/timeseries?metrics={metrics}&start_date={start_date}&end_date={end_date}" \
  -H "Authorization: Bearer $TOKEN"

Response 200 Timeseries samples

json

{
  "data": [
    {
      "timestamp": "2025-01-15T08:00:00Z",
      "metric": "heart_rate",
      "value": 72,
      "unit": "bpm"
    },
    {
      "timestamp": "2025-01-15T08:05:00Z",
      "metric": "heart_rate",
      "value": 74,
      "unit": "bpm"
    },
    {
      "timestamp": "2025-01-15T08:10:00Z",
      "metric": "heart_rate",
      "value": 68,
      "unit": "bpm"
    },
    {
      "timestamp": "2025-01-15T08:00:00Z",
      "metric": "heart_rate_variability",
      "value": 42,
      "unit": "ms"
    },
    {
      "timestamp": "2025-01-15T08:05:00Z",
      "metric": "heart_rate_variability",
      "value": 45,
      "unit": "ms"
    }
  ]
}