Skip to content
Browse documentation
Read data / ATH documentation

ath series

Read daily summaries or individual measurement samples.

Usage

$ath series heart_rate

Arguments

<quantity>
Required. A recorded quantity such as heart_rate. ath stats lists available data; ath series --help lists supported quantities.

What it does

Reads dense measurements from SQLite. The default output is one summary row per calendar day; --raw returns individual samples. It does not replace provider summaries or modify athlete data.

Examples

Choose a quantity and source ID found in ath stats. Date filters accept YYYY-MM-DD or an exact UTC timestamp. Calendar days use the saved athlete timezone or an explicit --timezone. Results are limited to 10,000 samples by default.

$ath series heart_rate --from 2026-08-24 --to 2026-08-30
$ath series heart_rate --source apple-watch-1 --raw --json

Options

--from <date>
earliest day to include (YYYY-MM-DD)
--to <date>
latest day to include (YYYY-MM-DD)
--source <id>
one device only, for when two measured the same thing — ath stats lists the ids
--timezone <name>
IANA timezone for calendar days; defaults to the athlete profile
--limit <count>
maximum samples to read
--raw
every sample, rather than one row per day
--json
structured output, for an agent rather than a person
--file <path>
read a file other than the one in this folder

Related commands

Up nextath check →