Withings
Query Withings body measurements, activity, sleep, and workout data via the bundled withings CLI.
When to Use
Activate when the user asks about their Withings data:
- Body metrics (weight, BMI, body fat, blood pressure, heart rate)
- Daily activity (steps, calories, distance, active duration)
- Sleep sessions (score, stages, duration, breathing rate)
- Workout sessions (run/walk/cycle/etc.)
Tooling
Three subcommands cover most needs:
| Subcommand |
Purpose |
withings status |
Connection state ({ok, status, connect_url?, disconnect_url?, reason?}). |
withings list-fields --category <CAT> |
Field list for a category (snake_case, units in the name). |
withings query --category <CAT> --start-date <YYYY-MM-DD> [--end-date --interval --fields] |
Typed snake_case records. Returns a JSON array. |
Categories
daily-metrics — Daily rollup of Activity (steps/calories/distance/HR) + Measures (weight/BP/body composition). Supports --interval hourly|daily|weekly (defaults to daily). Aggregation rules: sum for counters (step_count, active_energy_burned_kcal, distance_walking_running_meters), avg for hr_average_bpm, max for hr_max_bpm, last-of-bucket for body measurements (weight/BP/body fat etc.).
sleep — One row per sleep session (score, stages, duration, HR, breathing).
workout — One row per workout session (translated workout_type name, duration, distance, calories, HR).
Use list-fields to discover available fields per category.
Output
JSON to stdout. Datetimes are local YYYY-MM-DD HH:MM:SS per record's timezone. Session rows include id (prefixed withings_<id>), start_datetime, end_datetime, timezone. daily-metrics buckets include date / hour / week_start + record_count instead of id.
Examples
# Recent workouts
withings query --category workout --start-date 2026-05-01
# Weight trend (last reading per day)
withings query --category daily-metrics --start-date 2026-04-01 --fields body_mass_kg
# Weekly step totals
withings query --category daily-metrics --start-date 2026-04-01 --interval weekly --fields step_count
Auth
Before any Withings API call:
- Run
withings status.
- If
status is not_connected, share [Connect Withings](<connect_url>) exactly — never paste the raw URL.
- After the user completes the callback, re-run
withings status and proceed only when connected.
For disconnect: run withings disconnect and share [Disconnect Withings](<disconnect_url>) if present.
Never print tokens or credentials.
Operating Rules
- Treat linking as one-time onboarding — don't re-prompt for auth unless calls keep failing.
- Prefer
query --category <CAT> over the legacy commands. Field names are snake_case with units in the name (body_mass_kg, step_count, hr_average_bpm, sleep_total_duration_sec) — never expose Withings's numeric meas-type IDs to the user.
- If unsure of a field name, run
withings list-fields --category <CAT> BEFORE composing query --fields. Withings-native names (calories, distance, hr_average, weight) are NOT valid — they're translated to snake_case with units (energy_burned_kcal, distance_meters, hr_average_bpm, body_mass_kg). An empty filter result usually means the field name was wrong, not that the data is missing.
- Default to the last 7 days when the user asks for recent trends without specifying dates.
- For broad trends, use
--category daily-metrics --interval weekly instead of pulling every reading. The --interval flag already aggregates per the rules above — do NOT apply additional aggregation (sum/avg) to the bucketed output client-side.
- If
query returns [], say so clearly — never invent values. If the user is asking for a metric not surfaced by list-fields, drop to the legacy escape hatch (measures --meas-types <ID> or a more specific subcommand like heart-list; see references/commands.md for the meas-type ID table).
Legacy / Advanced Commands
Pre-query per-endpoint passthroughs that return raw {ok, status, body: <Withings native>} envelopes. Use only as an escape hatch for data not exposed by query — e.g. a meas-type missing from the translation table (withings measures --meas-types 130 for AFib ECG result), high-frequency sleep sensor data (withings sleep), or ECG signals (withings heart-list / heart-get).
Quick reference for the other passthroughs:
withings activity — raw daily Activity rows.
withings sleep-summary — raw nightly sleep summaries with Withings-native field names.
withings intraday — minute-resolution activity sensor data.
withings devices — list paired Withings devices.
Full command matrix, meas-type IDs, and Withings → Muse field mapping: references/commands.md.
1---2name: "withings"3description: "Use when linking Withings or reading Withings body measurements, activity, sleep, workout, heart, and intraday data."4icon: "withings"5metadata:6 source: https://skillmd.com/skills/win4r/withings7 includeInPrompt: false8---910# Withings1112Query Withings body measurements, activity, sleep, and workout data via the bundled `withings` CLI.1314## When to Use1516Activate when the user asks about their Withings data:17- Body metrics (weight, BMI, body fat, blood pressure, heart rate)18- Daily activity (steps, calories, distance, active duration)19- Sleep sessions (score, stages, duration, breathing rate)20- Workout sessions (run/walk/cycle/etc.)2122## Tooling2324Three subcommands cover most needs:2526| Subcommand | Purpose |27|---|---|28| `withings status` | Connection state (`{ok, status, connect_url?, disconnect_url?, reason?}`). |29| `withings list-fields --category <CAT>` | Field list for a category (snake_case, units in the name). |30| `withings query --category <CAT> --start-date <YYYY-MM-DD> [--end-date --interval --fields]` | Typed snake_case records. Returns a JSON array. |3132### Categories3334- `daily-metrics` — Daily rollup of Activity (steps/calories/distance/HR) + Measures (weight/BP/body composition). Supports `--interval hourly|daily|weekly` (defaults to `daily`). Aggregation rules: **sum** for counters (`step_count`, `active_energy_burned_kcal`, `distance_walking_running_meters`), **avg** for `hr_average_bpm`, **max** for `hr_max_bpm`, **last-of-bucket** for body measurements (weight/BP/body fat etc.).35- `sleep` — One row per sleep session (score, stages, duration, HR, breathing).36- `workout` — One row per workout session (translated `workout_type` name, duration, distance, calories, HR).3738Use `list-fields` to discover available fields per category.3940### Output4142JSON to stdout. Datetimes are local `YYYY-MM-DD HH:MM:SS` per record's timezone. Session rows include `id` (prefixed `withings_<id>`), `start_datetime`, `end_datetime`, `timezone`. `daily-metrics` buckets include `date` / `hour` / `week_start` + `record_count` instead of `id`.4344### Examples4546```bash47# Recent workouts48withings query --category workout --start-date 2026-05-014950# Weight trend (last reading per day)51withings query --category daily-metrics --start-date 2026-04-01 --fields body_mass_kg5253# Weekly step totals54withings query --category daily-metrics --start-date 2026-04-01 --interval weekly --fields step_count55```5657## Auth5859Before any Withings API call:601. Run `withings status`.612. If `status` is `not_connected`, share `[Connect Withings](<connect_url>)` exactly — never paste the raw URL.623. After the user completes the callback, re-run `withings status` and proceed only when `connected`.6364For disconnect: run `withings disconnect` and share `[Disconnect Withings](<disconnect_url>)` if present.6566Never print tokens or credentials.6768## Operating Rules69701. Treat linking as one-time onboarding — don't re-prompt for auth unless calls keep failing.712. Prefer `query --category <CAT>` over the legacy commands. Field names are snake_case with units in the name (`body_mass_kg`, `step_count`, `hr_average_bpm`, `sleep_total_duration_sec`) — never expose Withings's numeric meas-type IDs to the user.723. **If unsure of a field name, run `withings list-fields --category <CAT>` BEFORE composing `query --fields`.** Withings-native names (`calories`, `distance`, `hr_average`, `weight`) are NOT valid — they're translated to snake_case with units (`energy_burned_kcal`, `distance_meters`, `hr_average_bpm`, `body_mass_kg`). An empty filter result usually means the field name was wrong, not that the data is missing.734. Default to the last 7 days when the user asks for recent trends without specifying dates.745. For broad trends, use `--category daily-metrics --interval weekly` instead of pulling every reading. The `--interval` flag already aggregates per the rules above — do NOT apply additional aggregation (sum/avg) to the bucketed output client-side.756. If `query` returns `[]`, say so clearly — never invent values. If the user is asking for a metric not surfaced by `list-fields`, drop to the legacy escape hatch (`measures --meas-types <ID>` or a more specific subcommand like `heart-list`; see [references/commands.md](references/commands.md) for the meas-type ID table).7677## Legacy / Advanced Commands7879Pre-`query` per-endpoint passthroughs that return raw `{ok, status, body: <Withings native>}` envelopes. Use only as an **escape hatch** for data not exposed by `query` — e.g. a meas-type missing from the translation table (`withings measures --meas-types 130` for AFib ECG result), high-frequency sleep sensor data (`withings sleep`), or ECG signals (`withings heart-list` / `heart-get`).8081Quick reference for the other passthroughs:82- `withings activity` — raw daily Activity rows.83- `withings sleep-summary` — raw nightly sleep summaries with Withings-native field names.84- `withings intraday` — minute-resolution activity sensor data.85- `withings devices` — list paired Withings devices.8687Full command matrix, meas-type IDs, and Withings → Muse field mapping: [references/commands.md](references/commands.md).