Report whether a valid WHOOP token is held, its scopes and its expiry.

Call this first when a data tool fails; it distinguishes "never logged in" from "token expired" from "scope not granted".

Return a URL the user must open in a browser to authorise this server.

The user completes the WHOOP consent screen, is redirected to the configured redirect URI, and then passes the code and state query parameters back via whoop_complete_login.

Finish a login using the code and state from the redirect URL.

Args: code: The code query parameter from the redirect. state: The state query parameter from the redirect. It is verified against the pending login before the code is used.

Delete the locally stored WHOOP token.

This does not revoke the grant at WHOOP; do that from the WHOOP app under Settings if you want the authorisation itself withdrawn.

Return the user's WHOOP profile: user id, email, first and last name.

Return height in metres, weight in kilograms and max heart rate in bpm.

List recovery records: recovery score (%), HRV (ms) and resting heart rate (bpm).

Args: start: ISO 8601 start of the range, e.g. "2026-07-01T00:00:00Z". Defaults, with end, to the last 7 days when both are omitted. end: ISO 8601 end of the range. limit: Records to return, capped at 25 per page by WHOOP. next_token: Cursor from a previous truncated response, to continue that page.

List sleep records: performance (%), efficiency, and stage durations in milliseconds.

Args: start: ISO 8601 start of the range. Defaults, with end, to the last 7 days when both are omitted. end: ISO 8601 end of the range. limit: Records to return, capped at 25 per page by WHOOP. next_token: Cursor from a previous truncated response, to continue that page. detail: "summary" (default) omits the per-stage sleep-duration breakdown to keep the response small; "full" includes it under "stage_durations", with the units declared once in a top-level "units" key.

List physiological cycles: day strain (0-21), average and max heart rate, kilojoules.

A cycle is WHOOP's notion of a day, bounded by sleep rather than by midnight, and is the key other records join on.

Args: start: ISO 8601 start of the range. Defaults, with end, to the last 7 days when both are omitted. end: ISO 8601 end of the range. limit: Records to return, capped at 25 per page by WHOOP. next_token: Cursor from a previous truncated response, to continue that page.

List workouts: sport, strain, average and max heart rate, and heart-rate zone durations.

Args: start: ISO 8601 start of the range. Defaults, with end, to the last 7 days when both are omitted. end: ISO 8601 end of the range. limit: Records to return, capped at 25 per page by WHOOP. next_token: Cursor from a previous truncated response, to continue that page. detail: "summary" (default) omits the per-zone heart-rate duration breakdown to keep the response small; "full" includes it under "zone_durations", with the units declared once in a top-level "units" key.

Return a single sleep by its v2 UUID.

Return a single workout by its v2 UUID.

Summarise recovery, sleep and strain over a date range.

Returns mean, standard deviation, median, min and max for each metric, along with the number of scored records behind each figure and days_missing -- how many calendar days in the range have no scored record for that metric, a coverage gap rather than a record count.

Args: start: ISO 8601 start of the range. end: ISO 8601 end of the range.

Compute the direction and rate of change of one metric over a range.

Args: metric: One of "recovery_score", "hrv", "resting_heart_rate", "sleep_performance", "sleep_efficiency", "strain". start: ISO 8601 start of the range. end: ISO 8601 end of the range.

Returns the least-squares slope in metric units per day. A slope is a description of the window requested, not a forecast. Also returns an r² fit-quality figure for that slope -- both as the number and as a word ("strong"/"moderate"/"weak"/"negligible") -- and 7/30/90-day rolling means of the metric over calendar days.

Correlate two metrics over a range, sweeping a range of day-offsets.

Joins the two metrics by UTC calendar date rather than by cycle, and reports Pearson's r and Spearman's rho at every lag from -lag_days to +lag_days (inclusive), each with its own sample size. A positive lag means metric_a's date precedes metric_b's by that many days -- metric_a "leads". A lag whose surviving pairs fall below 8 is reported as refused rather than omitted.

Correlation here is descriptive, not causal: WHOOP daily samples are autocorrelated (today's recovery is not independent of yesterday's), so do not read a strong r at some lag as proof that one metric drives the other, and do not treat a handful of weeks as a stable finding.

Args: metric_a: First metric name, as in metric_trend. metric_b: Second metric name. start: ISO 8601 start of the range. end: ISO 8601 end of the range. lag_days: Sweep radius in days (default 3, capped at 14); the sweep covers every integer lag from -lag_days to +lag_days.

Raises: ValueError: if lag_days is negative.

Compare every summary metric between a baseline period and a later one.

Useful for "did the training block change anything" questions. Returns both periods' summaries and the delta, with sample sizes.

Args: baseline_start: ISO 8601 start of the baseline period. baseline_end: ISO 8601 end of the baseline period. comparison_start: ISO 8601 start of the comparison period. comparison_end: ISO 8601 end of the comparison period.