| get_activities_by_dateA | Get activities between specified dates with pagination support. For accounts with large activity histories, broad date ranges can return
thousands of activities in a single response. Use page and page_size to
retrieve activities in manageable chunks and avoid "result too large" errors.
Activities are ordered newest-first.
Pagination: when has_more is true the response includes next_page — pass
that value as page on the next call to retrieve the following page. Repeat
until has_more is false.
Note: total_count for a date range is not available from the Garmin API
without fetching all results. Use has_more / next_page to walk pages.
Each activity includes an event_type field with values such as:
- "race" — explicitly tagged as a race by the user
- "training" — explicitly tagged as a training activity
- "uncategorized" — no event type set; common for Peloton imports and
untagged outdoor runs. Distinct from "training":
filter for races with event_type == "race" rather
than excluding "training", since many non-race
activities appear as "uncategorized" not "training"
- field absent — API returned no eventType for this activity; not
observed in practice in any activity back to 2012
(oldest activities sampled on this account)
Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
activity_type: Optional activity type filter (e.g., cycling, running, swimming)
page: Zero-based page number (default 0)
page_size: Number of activities per page, max 200 (default 100)
|
| get_activities_fordateC | Get activities for a specific date Args:
date: Date in YYYY-MM-DD format
|
| get_activityA | Get detailed information for a single activity. Returns a comprehensive summary including timing, distance, heart rate,
elevation, training effect, and an event_type field. Common event_type
values: "race", "training", "uncategorized" (no event type set by the
user). The field is omitted when Garmin returns no eventTypeDTO.
Args:
activity_id: ID of the activity to retrieve
|
| set_activity_nameB | Set or update the name of an activity. Args:
activity_id: ID of the activity to update
activity_name: New activity name. Max 200 characters; Garmin rejects longer.
|
| set_activity_typeA | Change the activity type (sport) of an activity. Useful for reclassifying a mislabelled activity, e.g. flipping a run
logged as 'trail_running' to 'running', or a 'treadmill_running' walk to
'treadmill_walking'. Call get_activity_types to see all valid type keys.
Args:
activity_id: ID of the activity to update
type_key: Target activity type key (e.g. 'running', 'trail_running',
'treadmill_running', 'cycling', 'lap_swimming')
|
| set_activity_descriptionA | Set or update the free-text description (notes) of an activity. This is the notes field shown on the activity page — useful for
recording how a session felt, kit used, conditions, niggles, etc.
Pass an empty string to clear an existing description.
Args:
activity_id: ID of the activity to update
description: New description text (empty string clears it).
Max 2000 characters; Garmin rejects longer.
Emoji and other non-BMP characters count as two.
|
| set_activity_event_typeB | Set the event type of an activity. Event type categorises the activity's purpose. Valid keys:
race, recreation, specialEvent, training, transportation, touring,
geocaching, fitness, uncategorized.
Args:
activity_id: ID of the activity to update
event_type: Target event type key (e.g. 'race', 'training')
|
| set_perceived_effortA | Set the perceived effort (RPE) for an activity. Mirrors Garmin Connect's 'Perceived Effort' rating on a 0-10 scale,
where 0 clears the rating. Internally Garmin stores this multiplied by
10 (so RPE 7 is stored as 70); this tool handles the conversion.
Args:
activity_id: ID of the activity to update
rpe: Perceived effort from 0 to 10 (0 clears the rating)
|
| set_activity_feelB | Set how an activity felt ('How did you feel?'). Mirrors Garmin Connect's 5-point feel rating, stored as one of:
0 = very tired / poor
25 = tired
50 = normal
75 = good
100 = strong
Higher is better.
Args:
activity_id: ID of the activity to update
feel: One of 0, 25, 50, 75, 100
|
| get_activity_splitsC | Get splits for an activity Lap and nested length start_time_gmt timestamps are GMT (UTC).
Args:
activity_id: ID of the activity to retrieve splits for
|
| get_activity_typed_splitsC | Get typed splits for an activity Args:
activity_id: ID of the activity to retrieve typed splits for
|
| get_activity_split_summariesC | Get split summaries for an activity Args:
activity_id: ID of the activity to retrieve split summaries for
|
| get_activity_weatherA | Get weather data for an activity. Garmin's weather endpoint returns temperatures in Fahrenheit (from the
weather-station source) with no unit indicator, regardless of account
settings. This tool converts them to the account's display unit: metric
accounts get Celsius, statute_us accounts keep Fahrenheit. The
temperature_unit field ("F" or "C") states which unit was returned.
Wind speed, unlike temperature, is already returned in the account's
display unit (km/h for metric, mph for statute_us), so it is passed
through unconverted and labeled via the wind_speed_unit field.
Args:
activity_id: ID of the activity to retrieve weather data for
|
| get_activity_hr_in_timezonesC | Get heart rate data in different time zones for an activity Args:
activity_id: ID of the activity to retrieve heart rate time zone data for
|
| get_activity_power_in_timezonesA | Get power distribution across training zones for an activity. Returns time spent in each power zone with watt thresholds and duration.
Requires a power meter. Zones are based on the athlete's FTP configured in Garmin Connect.
Args:
activity_id: ID of the activity to retrieve power zone data for
|
| get_activity_gearC | Get gear data used for an activity Args:
activity_id: ID of the activity to retrieve gear data for
|
| get_activity_exercise_setsC | Get exercise sets for strength training activities Args:
activity_id: ID of the activity to retrieve exercise sets for
|
| set_activity_exercise_setsA | Replace the exercise sets on a strength (or other rep-counting) activity. Writes Garmin's structured per-set data, the same grid the Garmin Connect
"Edit sets" screen saves, so the sets feed Garmin's exercise history,
volume and muscle-map charts. This OVERWRITES every existing set,
including watch-detected sets and their recorded timing; to keep some,
read them with get_activity_exercise_sets and include them in the list.
When the watch already recorded the right sets but misidentified the
exercises, pass keep_timing=True: the existing sets keep their start
times, durations and rest periods, and only the exercise, reps and
weight are replaced, in order. The number of sets must match the
activity's recorded active sets, and duration_seconds/rest_seconds are
ignored.
Exercises must use Garmin's own keys. category is an exercise category
(e.g. DEADLIFT, BENCH_PRESS, PULL_UP, SQUAT) and exercise_name an
exercise within it (e.g. BARBELL_DEADLIFT, ROMANIAN_DEADLIFT). Garmin
rejects anything else with "Invalid Category" or "Invalid Sub-Category",
and rejects the whole request, so a typo leaves the activity unchanged.
Valid keys, grouped by category, are in
https://connect.garmin.com/web-data/exercises/Exercises.json
Args:
activity_id: ID of the activity to update
sets: Active sets in the order performed. Each is a dict with:
category (required): Garmin exercise category key
exercise_name: Garmin exercise key within the category; omit to
record just the category
reps: Repetition count; omit for timed exercises
weight_kg or weight_lb: Load lifted; omit for bodyweight
duration_seconds: Time under work for the set
rest_seconds: Rest after this set, recorded as a REST set
keep_timing: Keep the recorded set timing and rest periods,
replacing only exercise, reps and weight (default False)
|
| count_activitiesA | Get total count of activities in the user's Garmin account Returns the total number of activities recorded. |
| get_activitiesA | Get activities with pagination support. Retrieves a paginated list of activities ordered newest-first. Use this
for browsing through large activity lists when you do not need to filter
by date range, or as a complement to get_activities_by_date.
Each activity includes an event_type field. Common values: "race",
"training", "uncategorized" (no event type set by the user — common for
Peloton imports and untagged runs). Filter for races with
event_type == "race" rather than excluding "training", as many non-race
activities appear as "uncategorized" rather than "training".
Args:
start: Starting index (default 0)
limit: Maximum number of activities to return (default 20, max 100)
|
| create_manual_activityA | Log a manual activity in Garmin Connect — useful for activities done without a watch. The type_key must match a Garmin activity type. Use get_activity_types to see
the full list. Common values: yoga, strength_training, meditation, indoor_cycling,
pilates, bouldering, fitness_equipment.
Args:
type_key: Activity type key (e.g. "yoga", "strength_training")
date: Date of the activity in YYYY-MM-DD format
duration_minutes: Duration of the activity in minutes
start_time: Start time as HH:MM (24-hour, default 09:00)
activity_name: Optional title; defaults to the type_key if not provided
distance_km: Distance in kilometres (default 0.0 for non-distance activities)
time_zone: IANA time zone for the activity (default UTC)
If a write fails with write_committed="unknown", check whether the
activity exists before retrying to avoid creating a duplicate.
|
| delete_activityA | Permanently delete an activity from Garmin Connect. This cannot be undone. Call once with confirm=false (the default) to
preview the activity, then call again with confirm=true to delete it.
confirm=true is the scripting equivalent of a force flag.
Args:
activity_id: ID of the activity to delete
confirm: Must be true to actually delete. Default false returns a preview.
|
| get_activity_typesA | Get all available activity types Returns a list of all activity types supported by Garmin Connect,
useful for filtering activities by type. |
| get_statsA | Get daily activity stats with curated essential metrics Returns a summary of daily health and activity data including steps,
calories, heart rate, stress, body battery, and sleep metrics.
Note: bmr_calories is Garmin's bmrKilocalories field -- per Garmin's
own documentation this is RMR (BMR plus sedentary-to-light movement),
not true basal metabolic rate. For the current date, all calorie and
duration fields are a partial-day accumulator (elapsed hours so far),
not a full-day total.
Args:
date: Date in YYYY-MM-DD format
|
| get_stats_rangeA | Get lightweight per-day calorie and step totals for a date range. Returns total/active/resting calories and steps for each day between
start_date and end_date, inclusive, instead of the full get_stats
payload per day. Use this for multi-day analysis (e.g. comparing
measured intake/expenditure against Garmin's calorie model) instead
of calling get_stats once per day.
resting_calories is Garmin's bmrKilocalories field -- per Garmin's
own documentation this is RMR (BMR plus sedentary-to-light movement),
not true basal metabolic rate.
is_partial is true for the current date, whose accumulator only
covers elapsed hours so far -- treating it as a full day will
overstate a mean. Days with no device data (e.g. before the account
existed, or future dates within the range) return has_data: false
and null values rather than zeros, so a missing day never silently
enters an average as zero.
Maximum range: 28 days per call (Garmin's own limit for this endpoint).
Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
|
| get_energy_balanceA | Estimate a composition-derived TDEE from logged intake, Garmin's
claimed expenditure, and body-composition change over a date range. Combines three signals Garmin exposes separately -- mean logged intake
(nutrition log), mean claimed expenditure (Garmin's total_calories from
daily stats), and a body-composition trend (weight and body-fat % from
smart-scale readings) -- into composition_derived_tdee, an estimate
independent of Garmin's calorie model:
composition_derived_tdee = mean_intake + implied_deficit, where
implied_deficit comes from the fitted rate of fat and fat-free mass
change, using the standard energy-density approximations
7700 kcal/kg fat and 1800 kcal/kg fat-free mass. These are body
composition literature estimates, not Garmin-provided or measured
values -- treat the result as a rough estimate, not a lab measurement.
difference_kcal_per_day (Garmin's claim minus this estimate) has at
least two explanations -- Garmin overestimating expenditure, or
under-logged intake, which is common -- and this tool cannot
distinguish between them.
The body-composition trend is fit by least-squares regression across
every qualifying scale reading in range, not just the first and last --
an endpoint-to-endpoint difference is fully determined by two
individual measurements and inherits all of their noise (a 0.5%
body-fat wobble, well within normal scale repeatability, can swing a
two-point estimate by over a hundred kcal/day). weight_change_kg,
fat_mass_change_kg, and lean_mass_change_kg in body_composition are
all fitted values (the fitted line's value at the last reading's day
offset minus its value at the first), not raw differences between the
observed_first_*/observed_last_* fields, which are the actual
readings for reference/sanity-checking, not what the change figures
are computed from -- fitted_first_weight_kg/fitted_last_weight_kg are
also included so fitted_last_weight_kg - fitted_first_weight_kg can be
checked against weight_change_kg directly.
implied_deficit_kcal_per_day is the slope of a single regression: for
each reading, compute -(fat_kg * 7700 + lean_kg * 1800) where
lean_kg = weight_kg - fat_kg, then fit that value against day offset.
This is mathematically identical to combining separately-fit fat and
lean slopes, but its standard error -- implied_deficit_uncertainty_kcal_per_day,
returned whenever more than 2 readings are used -- is that single
fit's own residual standard error, which is well-defined and
reproducible from the raw readings alone (fat_kg and lean_kg are both
derived from the same weight/body-fat pair per reading, so treating
their separately-fit slopes' errors as independent and combining them
after the fact, instead of fitting the combined series directly,
would not be reproducible from outside without also knowing that
assumption). Treat a deficit within roughly one standard error of
zero as indistinguishable from no change.
Below a minimum span, or when most of the fit's statistical leverage
sits in one tight cluster of readings taken within about 48 hours of
each other, the fitted trend is not reliable even with 3+ readings --
a close, low-noise pair inside that cluster makes the fit look
precise while the slope is still mostly an extrapolation from that
cluster to wherever the other reading(s) fall. When this gate fails,
body_composition is still returned (it's just the fitted line, always
checkable against the observed readings) but derived is omitted and
gate_note explains which condition failed. Prefer windows of 3+ weeks
with several readings spread across them, not clustered at one end.
Short windows are also dominated by water/glycogen shifts (which
carry little caloric weight, unlike true lean tissue), which biases
the fat-free-mass term; see assumptions.note.
Exclusions applied automatically, matching get_nutrition_summary_between_dates
and get_stats_range:
- Intake: days with no logged food (item_count 0) are excluded from
the mean, not counted as zero. Days with a low but nonzero
item_count remain included (excluding them requires judgment this
tool doesn't make unilaterally) but are called out in
low_item_count_dates so low-confidence days are visible rather than
silently blended into the mean. A window with many such days (or
many item_count-0 days) biases composition_derived_tdee downward --
check days_excluded_unlogged and low_item_count_dates before
comparing two windows against each other.
- Expenditure: days with no device data, and the current (partial)
day, are excluded from the mean.
- Body composition: only scale readings with both weight and body-fat
percentage are used (skips weight-only manual entries).
Needs at least 2 qualifying body-composition readings to derive a
trend, and to pass the span/leverage gate above to derive a TDEE from
it. With 0 or 1 readings, returns the intake/expenditure means and
whatever body composition data exists, but omits the derived TDEE.
Maximum range: 61 days per call.
Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
|
| get_user_summaryC | Get user summary data (compatible with garminconnect-ha) Args:
date: Date in YYYY-MM-DD format
|
| get_body_compositionB | Get body composition data for a single date or date range Args:
start_date: Date in YYYY-MM-DD format or start date if end_date provided
end_date: Optional end date in YYYY-MM-DD format for date range
|
| get_stats_and_bodyC | Get stats and body composition data Args:
date: Date in YYYY-MM-DD format
|
| get_steps_dataA | Get detailed steps data with 15-minute intervals Note: This returns full interval data (~14KB). For a compact summary,
use get_stats() which includes total_steps.
Args:
date: Date in YYYY-MM-DD format
|
| get_daily_stepsB | Get steps data for a date range Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
|
| get_training_readinessB | Get training readiness data with curated metrics Returns training readiness score and contributing factors.
Args:
date: Date in YYYY-MM-DD format
|
| get_body_batteryC | Get body battery data with events Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
|
| get_body_battery_eventsC | Get body battery events data Args:
date: Date in YYYY-MM-DD format
|
| get_blood_pressureC | Get blood pressure data Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
|
| get_floorsB | Get floors climbed data Args:
date: Date in YYYY-MM-DD format
|
| get_rhr_dayC | Get resting heart rate data Args:
date: Date in YYYY-MM-DD format
|
| get_heart_ratesA | Get full heart rate time-series data Note: This returns detailed 2-minute interval data (~25KB).
For a compact summary, use get_heart_rates_summary().
Args:
date: Date in YYYY-MM-DD format
|
| get_heart_rates_summaryA | Get heart rate summary with essential metrics (lightweight version) Returns a compact summary (~500 bytes) instead of full time-series data (~25KB).
Ideal for daily health checkups and LLM integrations.
Args:
date: Date in YYYY-MM-DD format
|
| get_hydration_dataC | Get hydration data Args:
date: Date in YYYY-MM-DD format
|
| get_sleep_dataA | Get full sleep data with all details Note: This returns detailed sleep data (~50KB).
For a compact summary, use get_sleep_summary().
Args:
date: Date in YYYY-MM-DD format
|
| get_sleep_summaryA | Get sleep summary with only essential metrics (lightweight version) This endpoint returns a compact summary of sleep data (~350 bytes) instead of
the full granular data (~50KB). Ideal for daily health checkups and LLM integrations
where the full time-series data would overwhelm the context window.
Args:
date: Date in YYYY-MM-DD format
|
| get_sleep_summary_rangeA | Get lightweight sleep summaries for every night in a date range. Returns the same curated metrics as get_sleep_summary (sleep score, duration,
sleep stages, HRV, resting HR, etc.) for each night between start_date and
end_date, inclusive. Use this instead of calling get_sleep_summary once per
night when analyzing sleep trends over weeks or months.
Note: Garmin Connect does not expose a native range endpoint for sleep, so
this makes one request per night internally. Recommended range: up to a
few weeks for quick checks. Maximum: 90 nights per call.
Empty nights are skipped; a failed request stops the range and returns
an error identifying the failed date.
Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
|
| get_stress_dataA | Get full stress time-series data Note: This returns detailed interval data (~35KB) including body battery.
For a compact summary, use get_stress_summary().
Args:
date: Date in YYYY-MM-DD format
|
| get_stress_summaryA | Get stress summary with essential metrics (lightweight version) Returns a compact summary (~400 bytes) instead of full time-series data (~35KB).
Ideal for daily health checkups and LLM integrations.
Args:
date: Date in YYYY-MM-DD format
|
| get_respiration_dataA | Get full respiration time-series data Note: This returns detailed interval data (~20KB).
For a compact summary, use get_respiration_summary().
Args:
date: Date in YYYY-MM-DD format
|
| get_respiration_summaryA | Get respiration summary with essential metrics (lightweight version) Returns a compact summary (~300 bytes) instead of full time-series data (~20KB).
Args:
date: Date in YYYY-MM-DD format
|
| get_spo2_dataC | Get SpO2 (blood oxygen) data Args:
date: Date in YYYY-MM-DD format
|
| get_all_day_stressC | Get all-day stress data Args:
date: Date in YYYY-MM-DD format
|
| get_all_day_eventsC | Get daily wellness events data Args:
date: Date in YYYY-MM-DD format
|
| get_lifestyle_logging_dataB | Get lifestyle logging data for a specific date Returns lifestyle logging data which allows users to track behaviors
and their impact on health metrics.
Args:
date: Date in YYYY-MM-DD format
|
| get_weekly_stepsA | Get weekly step data aggregates Returns weekly step totals for the specified number of weeks ending at end_date.
Args:
end_date: End date in YYYY-MM-DD format
weeks: Number of weeks to fetch (default 4, max 52)
|
| get_weekly_stressB | Get weekly stress data aggregates Returns weekly stress values for the specified number of weeks ending at end_date.
Args:
end_date: End date in YYYY-MM-DD format
weeks: Number of weeks to fetch (default 4, max 52)
|
| get_weekly_intensity_minutesA | Get weekly intensity minutes data aggregates Returns weekly intensity minutes (moderate and vigorous) for the specified
number of weeks ending at end_date. total_minutes counts each vigorous
minute twice (moderate + 2 x vigorous), as Garmin does, so it is the
figure to compare against weekly_goal; moderate_minutes and
vigorous_minutes are the raw, unweighted minutes.
Args:
end_date: End date in YYYY-MM-DD format
weeks: Number of weeks to fetch (default 4, max 52)
|
| get_morning_training_readinessA | Get morning training readiness score Returns the morning training readiness assessment, which evaluates
recovery status and readiness to train based on overnight metrics.
Fields match one get_training_readiness entry (the snapshot taken
right after waking).
Args:
date: Date in YYYY-MM-DD format
|
| get_recovery_time_remainingA | Get remaining recovery time in hours for a day. This is the Firstbeat recovery clock shown on-device, distinct from
Training Readiness score (missing on some devices such as Forerunner 255)
and from Training Status ACWR. Training Readiness values are snapshots:
remaining_hours and state describe the snapshot at as_of (Garmin's local
timestamp when available), not a live countdown. remaining_hours_at_snapshot
retains the same value explicitly. For today only, when snapshots are
absent, the tool estimates remaining recovery by decaying recent activity
assignments and reports the estimate's as_of time. Today uses the server's
local date. Request failures are reported as errors, or source_errors when
another source supplies usable data.
Args:
date: Date in YYYY-MM-DD format. Defaults to today.
|
| get_full_nameA | Get user's full name from profile |
| get_unit_systemB | Get user's preferred unit system from profile |
| get_user_profileC | Get user profile information |
| get_userprofile_settingsC | Get user profile settings |
| get_heart_rate_zonesA | Get the user's saved heart-rate training-zone configuration. Garmin stores a generic DEFAULT profile plus optional sport-specific
overrides such as RUNNING and CYCLING. With no sport, this returns every
saved profile; pass a sport key to return just that profile.
Args:
sport: Optional Garmin sport key (for example default, running, or
cycling). "generic" is accepted as an alias for DEFAULT.
|
| set_heart_rate_zonesA | Set an account-level heart-rate training-zone configuration for one sport. WARNING: This mutates the user's Garmin Connect account configuration.
Garmin stores zones per sport, so DEFAULT (the generic fallback),
RUNNING, CYCLING, and other sport profiles are independent. Only the
requested sport is written; omitted values are read from that sport's
current configuration and preserved.
This change affects future activity recording and zone-based training.
It does NOT retroactively re-slice already-recorded activities: their
heart-rate zone boundaries were baked in when those activities were
recorded.
The calculation method may be max_hr (% maximum heart rate), hrr or
karvonen (% heart-rate reserve), lthr (% lactate-threshold heart rate),
or custom_bpm. Manual zone_boundaries are only accepted with the
custom_bpm method. Garmin's API does not persist a separate CUSTOM enum:
direct-BPM zones are sent and read back with trainingMethod=HR_MAX while
the explicit zone floors remain authoritative.
Changing the method or reference heart rates preserves the existing
zone floors; this tool does not calculate new percentage-based floors.
The tool performs a read-modify-write and then re-fetches the requested
sport. Its result is the configuration Garmin actually saved, not the
request payload. If verification fails after Garmin accepts the write,
it reports success with write_committed=true, a confirmation_error, and
the submitted_configuration. Re-read the profile before another update.
Args:
sport: Garmin sport key, e.g. default/generic, running, or cycling.
max_hr: Maximum heart rate in BPM.
resting_hr: Resting heart rate in BPM. Supplying it disables Garmin's
resting-HR auto-update for this zone profile.
lactate_threshold_hr: Lactate-threshold heart rate (LTHR) in BPM.
calculation_method: max_hr, hrr/karvonen, lthr, or custom_bpm.
zone_boundaries: Five strictly increasing BPM floors [Z1, Z2, Z3,
Z4, Z5]. Every floor must be at most max_hr.
|
| get_devicesA | Get all Garmin devices associated with the user account |
| get_device_last_usedB | Get information about the last used Garmin device |
| get_device_settingsA | Get settings for a specific Garmin device Returns device configuration including time/date format, units,
activity tracking settings, and alarm information.
Args:
device_id: Device ID (optional; defaults to the most recently used
device when omitted; can be obtained from get_devices or
get_device_last_used)
|
| get_primary_training_deviceA | Get information about the primary training device Returns details about the device designated as primary for training
metrics, along with other wearable devices on the account. |
| get_device_solar_dataA | Get solar data for a specific device Returns a per-day summary of solar charging for devices with solar panels
(e.g., Instinct Solar, Fenix Solar): activity time gained from solar, and
the average/peak solar utilization and minutes with solar input across the
day's per-minute readings. Only applicable to solar-capable devices.
Args:
device_id: Device ID (can be obtained from get_devices)
date: Date in YYYY-MM-DD format
|
| get_device_alarmsB | Get alarms from all Garmin devices Returns all configured alarms with their schedules, sounds, and enabled status. |
| push_workout_to_deviceA | Send a workout from the workout library to a Garmin device Queues the workout in Garmin Connect's device message queue, the same
as "Send to Device" in the Garmin Connect app. The watch picks it up
at its next sync with Garmin Connect (phone app or Wi-Fi), so it does
not appear on the watch immediately. Scheduling a workout does not
need this: scheduled workouts reach the watch's calendar on their own.
Each call queues another copy, so do not push the same workout twice.
Args:
workout_id: ID of the workout to send (from get_workouts or upload_workout)
device_id: Device ID (optional; defaults to the most recently used
device; can be obtained from get_devices or get_device_last_used)
|
| get_gearA | Get all gear registered with the user account Returns complete gear inventory including free-text notes, usage statistics,
and default activity associations. The notes field is null when unavailable.
defaults maps each activity type (Garmin typeKey, e.g. "running") to the
names of its default gear.
A gear item's stats_error reports a failed usage-statistics request;
a null total_distance_km means Garmin did not provide a distance.
No parameters required - user profile is fetched automatically.
Args:
include_stats: Include usage statistics for each gear item (default True).
Set to False for faster response with large gear collections.
|
| add_gear_to_activityB | Associate gear with an activity Links a specific piece of gear (like shoes, bike, etc.) to an activity.
Args:
activity_id: ID of the activity
gear_uuid: UUID of the gear to add (get from get_gear)
|
| remove_gear_from_activityB | Remove gear association from an activity Unlinks a specific piece of gear from an activity.
Args:
activity_id: ID of the activity
gear_uuid: UUID of the gear to remove
|
| get_weigh_insC | Get weight measurements between specified dates Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
|
| get_daily_weigh_insC | Get weight measurements for a specific date Args:
date: Date in YYYY-MM-DD format
|
| delete_weigh_insA | Delete weight measurements for a specific date Permanently removes the selected day's weigh-ins. This cannot be undone.
Call once with confirm=false (the default) to preview the measurements,
then call again with confirm=true to delete them.
Args:
date: Date in YYYY-MM-DD format
delete_all: Whether to delete all measurements for the day
confirm: Set true after reviewing the preview to perform the deletion
|
| add_weigh_inB | Add a new weight measurement Args:
weight: Weight value
unit_key: Unit of weight ('kg' or 'lbs'; 'lb' is accepted as an alias)
|
| add_weigh_in_with_timestampsA | Add a new weight measurement with specific timestamps If both timestamps are omitted, the current time is used. If only
date_timestamp is given, the GMT timestamp is derived from it.
Args:
weight: Weight value
unit_key: Unit of weight ('kg' or 'lbs'; 'lb' is accepted as an alias)
date_timestamp: Local timestamp in format YYYY-MM-DDThh:mm:ss
(required if gmt_timestamp is given -- it sets the day the
weigh-in is recorded on)
gmt_timestamp: GMT timestamp in format YYYY-MM-DDThh:mm:ss
|
| get_goalsA | Get Garmin Connect goals (active, future, or past). Reads goals the way Garmin Connect's Goals page does, so named
distance/time targets (e.g. a monthly cycling mileage goal) are
included with their progress and remaining amounts. Falls back to
python-garminconnect's get_goals() if that request returns nothing.
Args:
goal_type: Type of goals to retrieve. Options: "active", "future", or "past"
|
| get_personal_recordC | Get personal records for user |
| get_earned_badgesB | Get earned badges for user |
| get_adhoc_challengesA | Get user-created social/group challenges (e.g., step competitions with friends) Returns challenges created by users to compete with connections. These are
different from official Garmin badge challenges.
Args:
start: Starting index for pagination (default 0)
limit: Maximum number of challenges to return (default 20, max 100)
|
| get_available_badge_challengesA | Get official Garmin badge challenges available to join Returns monthly/seasonal challenges from Garmin that the user can join.
These challenges award badges and points upon completion.
Args:
start: Starting index for pagination (starts at 1)
limit: Maximum number of challenges to return (default 20, max 100)
|
| get_badge_challengesA | Get badge challenges the user has completed. Returns the completed badge-challenge history and earned dates. For
challenges still in progress, use get_non_completed_badge_challenges.
Args:
start: Starting index for pagination (starts at 1)
limit: Maximum number of challenges to return (default 20, max 100)
|
| get_non_completed_badge_challengesA | Get badge challenges currently in progress (not yet completed) Returns active challenges the user has joined but hasn't completed yet.
Useful for tracking current progress toward badge goals.
Args:
start: Starting index for pagination (starts at 1)
limit: Maximum number of challenges to return (default 20, max 100)
|
| get_race_predictionsB | Get predicted race times based on current fitness level Returns Garmin's predictions for 5K, 10K, half marathon, and marathon
finish times based on the user's recent training data and VO2 max. |
| get_inprogress_virtual_challengesA | Get in-progress virtual challenges/expeditions Returns virtual challenges (like walking expeditions on famous trails)
that the user is currently participating in.
Args:
start: Starting index for pagination (default 1, must be >= 1;
garminconnect 0.3.2 rejects 0 for this endpoint)
limit: Maximum number of challenges to return (default 20, max 100)
|
| get_progress_summary_between_datesA | Get progress summary for a metric between dates Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
metric: Metric to get progress for (e.g., "elevationGain", "duration", "distance", "movingDuration", "calories")
Note: "calories" values are returned in kcal. Garmin's underlying
endpoint stores this metric pre-scaled by ~4.19; this tool undoes
that scaling before returning.
|
| get_hill_scoreC | Get hill score data between dates Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
|
| get_endurance_scoreC | Get endurance score data between dates Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
|
| get_training_effectB | Get training effect data for a specific activity. Uses activity details first. If Garmin returns HTTP 403 for that
endpoint (seen on valid, recent activities), falls back to activity
list search, which still includes aerobic/anaerobic training effect.
Args:
activity_id: ID of the activity to retrieve training effect for
|
| get_hrv_dataB | Get Heart Rate Variability (HRV) data Args:
date: Date in YYYY-MM-DD format
return_timeseries: If True, include detailed 5-minute HRV readings (can be large)
|
| get_fitnessage_dataA | Get fitness age data Args:
date: Date in YYYY-MM-DD format
details: If True, include component breakdown (BMI, RHR, vigorous activity)
with targets and improvement suggestions
|
| get_training_statusB | Get training status with curated metrics Returns comprehensive training status including load, VO2 max, recovery,
and training readiness indicators.
Args:
date: Date in YYYY-MM-DD format
|
| get_cycling_ftpB | Get the latest cycling Functional Threshold Power (FTP) data. Returns the most recent cycling FTP estimate available from Garmin. |
| get_lactate_thresholdA | Get lactate threshold data Returns lactate threshold information, which is the exercise intensity at
which lactate starts to accumulate in the blood. This is a key metric for
endurance training.
Args:
start_date: Start date in YYYY-MM-DD format (optional; give with
end_date for history, omit both for latest)
end_date: End date in YYYY-MM-DD format (optional; give with
start_date for history, omit both for latest)
|
| request_reloadC | Request reload of epoch data Args:
date: Date in YYYY-MM-DD format
|
| get_training_load_trendA | Get Garmin's daily acute and chronic training load over a date range. Returns, per day, Garmin's acute load (`atl`, the 7-day load), chronic load (`ctl`), their
difference (`tsb` = ctl - atl), and Garmin's Acute:Chronic Workload Ratio (`acwr`,
`acwr_status`). These are Garmin's dailyTrainingLoadAcute/Chronic values, not TrainingPeaks
CTL/ATL: they are on Garmin's weekly load scale, so `tsb` is not comparable to TrainingPeaks
TSB and TSB form thresholds do not apply. Use `acwr`/`acwr_status` (and the optimal chronic
load range) to judge whether load is building steadily or spiking.
Recommended range: 4-8 weeks. Maximum: 90 days.
Empty days are skipped; a failed daily request returns an error.
Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
|
| get_training_load_balanceA | Get Garmin's Load Focus — the distribution of the trailing-month
training load across Aerobic Low, Aerobic High, and Anaerobic intensity
bands, plus the system's feedback phrase (e.g. AEROBIC_HIGH_SHORTAGE,
BALANCED, ANAEROBIC_SHORTAGE). Use this to assess whether the athlete's training mix is balanced or
deficient in a particular intensity band. Each band reports its load
alongside Garmin's target range; a `status` of "below", "within", or
"above" is computed from the load relative to that range.
Garmin reports Load Focus per device. The primary activity tracker's
record is used when it can be identified; `load_device_id` and
`load_device_name` say which device the numbers came from.
Args:
date: Date in YYYY-MM-DD format
|
| get_hrv_trendA | Get HRV (Heart Rate Variability) trend over a date range. Returns daily HRV values and weekly rolling averages. Single-day HRV is too noisy
to act on — use this tool to identify baseline shifts that signal accumulated fatigue
or recovery. A drop of >10ms from the 7-day baseline warrants reducing training load.
Recommended range: 7-21 days. Maximum: 30 days.
Empty days are skipped; a failed daily request returns an error.
Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
|
| get_vo2max_trendA | Get VO2 max trend over a date range. Returns daily VO2 max estimates from Garmin's FirstBeat algorithm. Use this to track
whether training is producing fitness gains over weeks or months. Flat or declining
VO2 max over 4+ weeks suggests insufficient training stimulus or overreaching.
Note: VO2 max estimates are smoothed and update gradually — daily changes of <0.5
are within normal noise. Focus on the 4-6 week trend direction.
Garmin records a new VO2 max value only on days with a recompute (after an
activity). Days in between carry the last known value forward and are marked
with "carried_forward": true, matching the trend chart in Garmin Connect.
Dated status values retain their measurement date. data_points counts
displayed days, including carried-forward values.
If historical values are unavailable, the current profile estimate is returned
separately and is not represented as a historical trend point.
Endpoint-specific failures remain visible in request_errors when a
fallback succeeds. Authentication, rate-limit, and connection failures
stop the request.
Recommended range: 4-12 weeks. Maximum: 90 days.
Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
|
| get_respiration_trendA | Get overnight respiration rate trend over a date range. Elevated resting respiration rate (compared to personal baseline) is an early
warning sign for overreaching, illness, or poor recovery. Use this alongside HRV
trend for a complete recovery picture.
Recommended range: 7-21 days. Maximum: 30 days.
Empty days are skipped; a failed daily request returns an error.
Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
|
| get_running_toleranceA | Get Running Tolerance for a single day. Returns Garmin's running load capacity model: how much running load the
athlete can currently absorb (tolerance), the intensity-adjusted load
their recent runs have produced (acute load), and the raw distance behind
that load. All three are expressed in km so they're directly comparable —
`load_ratio` (acute_load_km / distance_km) quantifies how much intensity
is inflating the cost of each kilometer run.
Args:
date: Date in YYYY-MM-DD format
|
| get_running_tolerance_trendA | Get Running Tolerance trend over a date range. Running Tolerance moves slowly — its value is in the trajectory, not any
single day. Returns, per period: tolerance_km (current load capacity),
acute_load_km (intensity-adjusted load), distance_km (actual distance
run), and load_ratio (acute_load_km / distance_km — how much intensity
inflates the cost of each kilometer). Weekly aggregation (default) gives
a compact multi-month view; daily gives day-to-day resolution for a
shorter window.
Recommended range: 4-12 weeks. Maximum: 90 days for daily aggregation,
366 days for weekly (this endpoint returns the whole range in one call,
so the limit protects output size, not request volume).
Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
aggregation: "daily" or "weekly" (default "weekly")
|
| get_acclimationA | Get heat and altitude acclimation status for a given date. Garmin tracks how adapted the athlete currently is to training in heat
and at altitude. heat_acclimation_percent runs 0-100 and decays without
continued exposure; use it to judge readiness for a warm-weather race.
heat_trend reports Garmin's own label (e.g. ACCLIMATIZED). The
previous_* fields hold the prior reading so direction of travel is
visible without a second call.
VO2 max is not returned here; use get_training_status or get_vo2max_trend.
Args:
date: Date in YYYY-MM-DD format
|
| get_workoutsA | Get all workouts with curated summary list Returns a count and list of workout summaries with essential metadata only.
For detailed workout information including segments, use get_workout_by_id.
|
| get_workout_by_idA | Get detailed information for a specific workout Returns workout details including segments and step structure.
Accepts either:
- Numeric workout ID (from get_workouts, get_scheduled_workouts, or
training-plan families that expose workout_id)
- Workout UUID (from adaptive Garmin Coach/training-plan workouts)
Rest-day UUIDs can resolve to a minimal record without a workout name
or segments.
Pace target values are speeds in meters per second. target_value_low
and target_value_high preserve Garmin's targetValueOne/targetValueTwo
order; they are not sorted by magnitude.
Args:
workout_id: Workout ID (numeric) or UUID (for training plan workouts)
raw: Return Garmin's full workout JSON (the DTO format upload_workout
describes) instead of the simplified summary, which leaves fields out.
|
| download_workoutC | Download a workout as a FIT file Downloads the workout in FIT format. The binary data cannot be returned
directly through the MCP interface, but this confirms the workout is available.
Args:
workout_id: ID of the workout to download
|
| upload_workoutA | Upload a workout from JSON data Creates a new workout in Garmin Connect from structured workout data.
IMPORTANT: Step types must use Garmin's DTO format:
- Use "ExecutableStepDTO" for regular steps (warmup, interval, cooldown, recovery)
- Use "RepeatGroupDTO" for repeat/interval groups with numberOfIterations.
Always include endCondition with conditionTypeId 7 and conditionTypeKey
"iterations"; omitting conditionTypeId causes the API to silently corrupt
the repeat count.
- stepOrder is one depth-first counter over the whole workout: a repeat
group takes the next number and its nested steps continue from there
(group 2, children 3 and 4, cooldown 5). Do not restart at 1 inside a group.
IMPORTANT: Heart rate targets come in two forms:
- Named zone (e.g. Zone 2): set targetType to "heart.rate.zone" and use "zoneNumber" (1-5).
Do NOT put the zone number in targetValueOne.
- Custom HR range (e.g. 105-143 bpm): set targetType to "heart.rate.zone" and use
"targetValueOne" (low bpm) / "targetValueTwo" (high bpm). Do NOT set "zoneNumber".
This matches Garmin Connect's "Custom" heart rate target.
For non-HR targets (pace, power, cadence), use targetValueOne/targetValueTwo directly.
Pace targets are speeds in meters per second, not min/km:
5:00/km = 1000 m / 300 s = 3.333 m/s.
Target values are fields on the workout step, alongside targetType; do not put
targetValueOne, targetValueTwo, or zoneNumber inside the targetType object.
Use either zoneNumber or targetValueOne/targetValueTwo, not both. Garmin silently
discards a custom range when a named zone is also present.
Note: a safety check converts targetValueOne 1-5 to zoneNumber when zoneNumber is missing,
to catch the common mistake of putting a zone index in targetValueOne. Typical bpm values
(e.g. 105, 143) are not affected.
IMPORTANT: Target type IDs and keys must match Garmin's canonical mapping.
Garmin treats workoutTargetTypeId as authoritative, so mismatches are rejected
before upload. Known mappings:
- workoutTargetTypeId 1 -> "no.target"
- workoutTargetTypeId 2 -> "power.zone" (cycling power zone 1-7, use zoneNumber)
- workoutTargetTypeId 4 -> "heart.rate.zone"
- workoutTargetTypeId 6 -> "pace.zone" (running/swim) OR "power.between" (cycling)
IMPORTANT: For cycling power targets use the correct target type:
- Power zone (zone 1-7 based on FTP %): use workoutTargetTypeId 2, key "power.zone",
and "zoneNumber" (1-7).
- Custom % FTP range (e.g. 76-81% FTP): use workoutTargetTypeId 2, key "power.zone",
"targetValueOne"/"targetValueTwo" as percentages and
"targetValueUnit": {"unitKey": "percent"}. Garmin Connect shows it as
"Custom Power 76-81% FTP" with the matching watts.
- Absolute watt range (e.g. 200-250 W): use workoutTargetTypeId 6, key "power.between",
and "targetValueOne" (low watts) / "targetValueTwo" (high watts).
Using workoutTargetTypeId 2 with key "power.between" is a silent Garmin bug: the
workout uploads but Garmin stores it as "power.zone" and the intent is lost.
Use {"workoutTargetTypeId": 4, "workoutTargetTypeKey": "heart.rate.zone"} with
targetValueOne/targetValueTwo for custom heart-rate ranges.
IMPORTANT: Sport type IDs for workouts (different from activity API!):
- 1 = running, 2 = cycling, 5 = strength_training, 6 = cardio_training, 12 = walking
IMPORTANT: End condition IDs and keys must match Garmin's canonical mapping.
Garmin treats conditionTypeId as authoritative, so mismatches such as
{"conditionTypeId": 4, "conditionTypeKey": "heart.rate"} are rejected before
upload because Garmin would interpret them as "calories". Use
{"conditionTypeId": 6, "conditionTypeKey": "heart.rate"} for heart-rate
end conditions.
**Available Templates:**
Instead of building workout JSON from scratch, you can use these MCP resources as starting points:
- workout://templates/simple-run - Basic warmup/run/cooldown structure
- workout://templates/interval-running - Interval training with repeat groups
- workout://templates/tempo-run - Tempo run with heart rate zone targets
- workout://templates/strength-circuit - Strength training with exercises, reps, rest
- workout://reference/structure - Complete JSON structure reference with all fields
Access these resources using your MCP client's resource reading capability, modify the template
as needed, and pass the resulting JSON as the workout_data parameter.
**Strength training workouts** require these additional fields on each exercise step:
- "category": exercise category (e.g. "BENCH_PRESS", "PULL_UP", "CURL", "SHOULDER_PRESS",
"ROW", "SQUAT", "DEADLIFT", "TRICEPS_EXTENSION", "PLANK", "LUNGE", "CARDIO")
- "exerciseName": specific exercise (e.g. "BARBELL_BENCH_PRESS", "PULL_UP",
"DUMBBELL_BICEPS_CURL", "DUMBBELL_SHOULDER_PRESS", "BENT_OVER_ROW_WITH_DUMBELL",
"BODY_WEIGHT_DIP", "BARBELL_SQUAT", "BARBELL_DEADLIFT")
- "weightValue" (optional): weight as number (e.g. 24.0)
- "weightUnit" (optional): {"unitId": 8, "unitKey": "kilogram", "factor": 1000.0}
Use endCondition reps (conditionTypeId: 10) for exercises, rest (stepTypeId: 5) between sets.
Example strength exercise step:
{
"type": "ExecutableStepDTO",
"stepOrder": 1,
"stepType": {"stepTypeId": 3, "stepTypeKey": "interval"},
"endCondition": {"conditionTypeId": 10, "conditionTypeKey": "reps"},
"endConditionValue": 10.0,
"targetType": {"workoutTargetTypeId": 1, "workoutTargetTypeKey": "no.target"},
"category": "BENCH_PRESS",
"exerciseName": "BARBELL_BENCH_PRESS",
"weightValue": 60.0,
"weightUnit": {"unitId": 8, "unitKey": "kilogram", "factor": 1000.0}
}
Example running workout with HR zone target:
{
"workoutName": "My Workout",
"sportType": {"sportTypeId": 1, "sportTypeKey": "running"},
"workoutSegments": [{
"segmentOrder": 1,
"sportType": {"sportTypeId": 1, "sportTypeKey": "running"},
"workoutSteps": [{
"type": "ExecutableStepDTO",
"stepOrder": 1,
"stepType": {"stepTypeId": 3, "stepTypeKey": "interval"},
"endCondition": {"conditionTypeId": 2, "conditionTypeKey": "time"},
"endConditionValue": 1200.0,
"targetType": {"workoutTargetTypeId": 4, "workoutTargetTypeKey": "heart.rate.zone"},
"zoneNumber": 3
}]
}]
}
Args:
workout_data: Dictionary containing workout structure (name, sport type, segments, etc.)
|
| upload_workoutsA | Upload multiple workouts from JSON data in a single call Creates multiple new workouts in Garmin Connect. Each item in the list
uses the same structure as upload_workout.
IMPORTANT: Step types must use Garmin's DTO format:
- Use "ExecutableStepDTO" for regular steps (warmup, interval, cooldown, recovery)
- Use "RepeatGroupDTO" for repeat/interval groups with numberOfIterations.
Always include endCondition with conditionTypeId 7 and conditionTypeKey
"iterations"; omitting conditionTypeId causes the API to silently corrupt
the repeat count.
- stepOrder is one depth-first counter over the whole workout: a repeat
group takes the next number and its nested steps continue from there
(group 2, children 3 and 4, cooldown 5). Do not restart at 1 inside a group.
IMPORTANT: For named heart rate zone targets, use "zoneNumber" (1-5), NOT targetValueOne/targetValueTwo.
For custom heart-rate ranges, use targetType {"workoutTargetTypeId": 4,
"workoutTargetTypeKey": "heart.rate.zone"} with targetValueOne/targetValueTwo.
Target values belong on the workout step, alongside targetType, not inside it.
For cycling power zone targets (zone-based), use workoutTargetTypeId 2, key "power.zone".
For cycling absolute watt range targets, use workoutTargetTypeId 6, key "power.between",
with targetValueOne (low watts) and targetValueTwo (high watts).
Pace targets use targetValueOne/targetValueTwo in meters per second, not
min/km: 5:00/km = 1000 m / 300 s = 3.333 m/s.
Target type IDs and keys must match Garmin's canonical mapping.
IMPORTANT: End condition IDs and keys must match Garmin's canonical mapping.
Garmin treats conditionTypeId as authoritative, so mismatches are rejected before upload.
Args:
workouts: List of workout dictionaries, each containing workout structure
(name, sport type, segments, etc.) — same format as upload_workout.
|
| delete_workoutA | Delete a workout from Garmin Connect Permanently removes a workout from your Garmin Connect workout library.
This cannot be undone. Call once with confirm=false (the default) to
preview the workout, then call again with confirm=true to delete it.
Args:
workout_id: ID of the workout to delete (get IDs from get_workouts)
confirm: Must be true to actually delete. Default false returns a preview.
|
| delete_workoutsA | Delete multiple workouts from Garmin Connect in a single call Permanently removes multiple workouts from your Garmin Connect workout library.
This cannot be undone. Call once with confirm=false (the default) to
preview the workouts, then call again with confirm=true to delete them.
Args:
workout_ids: List of workout IDs to delete (get IDs from get_workouts)
confirm: Must be true to actually delete. Default false returns a preview.
|
| get_scheduled_workoutsA | Get scheduled workouts between two dates with curated summary list Returns workouts that have been scheduled on the Garmin Connect calendar,
including their scheduled dates and completion status.
Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
|
| get_garmin_coach_workoutsA | Get Garmin Coach workouts around the given date Returns workouts from the active Garmin Coach/training plan, including
plan metadata, workout identifiers, dates, sport, duration, completion
status, rest days, race days, and workout intent when Garmin provides
them. Adaptive plans expose only Garmin's currently generated window,
typically the current week; future dates may return no workouts even
while a plan is active. The count includes rest-day entries.
Garmin's standalone Daily Suggested Workouts are generated on compatible
devices. As of July 31, 2026, no supported or known Garmin Connect
web/API endpoint, including those exposed by this project's
python-garminconnect dependency, returns the device's upcoming DSW
schedule. This tool returns Garmin Coach/training-plan workouts and does
not synthesize device-generated suggestions.
This is the preferred tool for Garmin Coach requests. The legacy
get_training_plan_workouts tool returns the same data; do not call both.
Adaptive Coach plans typically expose workout_uuid; other plan families
may expose numeric workout_id. Pass whichever identifier is present to
get_workout_by_id. Rest-day UUIDs may return minimal detail without
workout segments.
Args:
calendar_date: Reference date in YYYY-MM-DD format (returns week's workouts)
|
| get_training_plan_workoutsA | Compatibility alias for get_garmin_coach_workouts Prefer get_garmin_coach_workouts for new requests. This legacy tool
returns the same Garmin Coach/training-plan data; do not call both for
one request. Adaptive plans expose only Garmin's currently generated
window, typically the current week; future dates may return no workouts
even while a plan is active.
Adaptive training plans typically expose workout_uuid; other plan
families may expose numeric workout_id. Pass whichever identifier is
present to get_workout_by_id. The returned count includes rest days.
Args:
calendar_date: Reference date in YYYY-MM-DD format (returns week's workouts)
|
| schedule_workoutA | Schedule a workout to a specific calendar date This adds an existing workout from your Garmin workout library
to your Garmin Connect calendar on the specified date.
Idempotent: if the workout is already scheduled for that date, this
is a no-op that reports success without creating a duplicate entry.
Args:
workout_id: ID of the workout to schedule (get IDs from get_workouts)
calendar_date: Date to schedule the workout in YYYY-MM-DD format
|
| schedule_workoutsA | Schedule multiple workouts to specific calendar dates This adds workouts to your Garmin Connect calendar in a single call.
Each item can either reference an existing workout by ID, or provide
inline workout_data to upload-and-schedule in one step.
Args:
schedules: List of workout schedules, each with:
- calendar_date (str): Date to schedule the workout in YYYY-MM-DD format (required)
- workout_id (int): ID of an existing workout to schedule (required unless workout_data is provided)
- workout_data (dict): Inline workout JSON to upload first, then schedule (optional).
When provided, workout_id is not required. Uses the same structure and
target-value rules as upload_workout; pace targets are in m/s, not
min/km (5:00/km = 3.333 m/s).
Examples:
Schedule existing workouts by ID:
[{"workout_id": 123456, "calendar_date": "2024-01-15"},
{"workout_id": 789012, "calendar_date": "2024-01-17"}]
Upload and schedule inline:
[{"calendar_date": "2024-01-15", "workout_data": {"workoutName": "Easy Run", ...}},
{"workout_id": 789012, "calendar_date": "2024-01-17"}]
|
| reschedule_workoutA | Move a scheduled workout to another date on the Garmin Connect calendar Moves the existing calendar entry in place, so its id stays the same
and no duplicate entry is created. Prefer this over unschedule +
schedule. Safe to repeat: moving an entry to the date it is already
on changes nothing.
IMPORTANT: scheduled_workout_id is the calendar-entry id, which is
different from the workout's id. Get it from get_scheduled_workouts
(the "scheduled_workout_id" field), not from get_workouts.
Args:
scheduled_workout_id: Calendar-entry id from get_scheduled_workouts
calendar_date: New date in YYYY-MM-DD format
|
| unschedule_workoutA | Remove a scheduled workout from the Garmin Connect calendar Deletes a calendar entry without deleting the underlying workout
template — the workout stays in your library and can be re-scheduled.
IMPORTANT: scheduled_workout_id is the calendar-entry id, which is
different from the workout's id. Get it from get_scheduled_workouts
(the "scheduled_workout_id" field), not from get_workouts.
Note: the scheduled-workouts listing is an eventually-consistent index.
If you just scheduled this workout, allow a moment before unscheduling
so the id is available.
Args:
scheduled_workout_id: Calendar-entry id from get_scheduled_workouts
|
| unschedule_workoutsA | Remove multiple scheduled workouts from the Garmin Connect calendar Deletes multiple calendar entries in a single call. The underlying
workout templates are left intact in your library.
IMPORTANT: each id is a calendar-entry id (the "scheduled_workout_id"
field from get_scheduled_workouts), not a workout id.
Args:
scheduled_workout_ids: List of calendar-entry ids from get_scheduled_workouts
|
| add_body_compositionA | Add body composition data Args:
date: Date in YYYY-MM-DD format
weight: Weight in kg
percent_fat: Body fat percentage
percent_hydration: Hydration percentage
visceral_fat_mass: Visceral fat mass in kg (not grams)
bone_mass: Bone mass in kg (not grams)
muscle_mass: Muscle mass in kg (not grams)
basal_met: Basal metabolic rate in kcal/day
active_met: Active metabolic rate in kcal/day
physique_rating: Physique rating
metabolic_age: Metabolic age
visceral_fat_rating: Visceral fat rating
bmi: Body Mass Index
|
| set_blood_pressureC | Set blood pressure values Args:
systolic: Systolic pressure (top number)
diastolic: Diastolic pressure (bottom number)
pulse: Pulse rate
notes: Optional notes
|
| add_hydration_dataB | Add hydration data Args:
value_in_ml: Amount of liquid in milliliters
cdate: Date in YYYY-MM-DD format
timestamp: Timestamp in YYYY-MM-DDThh:mm:ss.sss format
|
| get_pregnancy_summaryC | Get pregnancy summary data |
| get_menstrual_data_for_dateC | Get menstrual data for a specific date Args:
date: Date in YYYY-MM-DD format
|
| get_menstrual_calendar_dataA | Get menstrual calendar data between specified dates Automatically chunks requests longer than 92 days, Garmin's
server-side limit, and stitches the responses together.
Identical records spanning a chunk boundary are returned once for list
and dict-of-list responses. Other payload shapes are returned per chunk.
Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
|
| get_nutrition_daily_food_logA | Get daily food consumption records for a date Returns food items logged throughout the day including calories,
macronutrients, and meal associations.
Args:
date: Date in YYYY-MM-DD format
|
| get_nutrition_summary_between_datesA | Get per-day nutrition totals for every day in a date range. Returns one lightweight entry per day (date, calories, carbs, protein,
fat, item_count) instead of the full per-item food log that
get_nutrition_daily_food_log returns for a single date. Use this for
multi-day intake analysis (e.g. mean intake for a TDEE estimate)
instead of calling get_nutrition_daily_food_log once per day.
item_count is the number of logged food items that day. A day with
item_count == 0 has no logged food at all, and a low but nonzero
item_count may mean only part of the day was logged (e.g. breakfast
only). Both cases read as low intake in the totals alone -- exclude
low-item_count days explicitly before averaging intake or deriving
TDEE; don't infer "unlogged" from a low calorie total.
Maximum range: 61 days per call (Garmin's own limit for this endpoint).
Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
|
| get_nutrition_daily_mealsA | Get daily meal summaries for a date Returns meal-level summaries (breakfast, lunch, dinner, snacks)
with nutritional totals for each meal. Each meal includes a mealId
needed for logging food items to that meal.
Args:
date: Date in YYYY-MM-DD format
|
| get_nutrition_daily_settingsB | Get nutrition plan/settings for a date Returns the user's nutrition goals and targets including
calorie targets, macronutrient goals, and plan configuration.
Args:
date: Date in YYYY-MM-DD format
|
| set_nutrition_daily_settingsA | Update daily nutrition goals (calorie target and macronutrient targets). Reads the current settings for the date, applies the supplied overrides,
and writes the merged result back. Only the fields you provide are
changed; omitted fields keep their existing values.
Macro arguments retain their existing names and are passed through to
Garmin's macroGoals without unit conversion. The endpoint's macro units
have not been independently verified. Returned goals come from Garmin's
response, or a settings read-back when the update has no response body.
Args:
date: Date in YYYY-MM-DD format (settings are typically set once and
inherited across days, but Garmin accepts per-day overrides)
calorie_goal: Daily calorie target in kcal
carbs_grams: Daily carbohydrate target in grams
fat_grams: Daily fat target in grams
protein_grams: Daily protein target in grams
target_date: Optional new target date (YYYY-MM-DD) for the weight
goal that this endpoint carries. Only needed when the stored
target date has already passed, which otherwise makes Garmin
reject the update; must be after `date`.
|
| search_foodsA | Search Garmin's general food catalog (FatSecret + Garmin custom foods) Searches across the entire food catalog including FatSecret-sourced
branded and generic foods, not just the user's Garmin custom foods.
Use this to find branded packaged foods by name before logging them.
Returns food_id, source, name, brand, and all available servings with
macros. The source field ("FATSECRET" or "GARMIN") and food_id together
identify the right routing for log_custom_food — pass both to
log_custom_food's food_id and source parameters respectively.
For the user's own custom foods only, use get_custom_foods instead.
Args:
query: Food name or brand to search for (e.g. "Cheerios", "Greek yogurt")
start: Starting index for pagination (default 0)
limit: Maximum number of results per page (default 20)
|
| get_custom_foodsA | Search or list user's custom foods Returns custom foods the user has created. Use the search parameter
to find existing foods by name before creating duplicates — the
response includes foodId and servingId needed for log_custom_food.
For branded catalog foods (FatSecret), use search_foods instead.
Args:
search: Search term to filter foods by name (default: list all)
start: Starting index for pagination (default 0)
limit: Maximum number of results (default 20)
|
| get_custom_food_serving_unitsA | Get available serving units for custom foods Returns the list of valid serving units (e.g. G, ML, OZ)
that can be used when creating custom foods. |
| create_custom_foodA | Create a custom food in the user's Garmin nutrition library Creates a new food item with nutritional information per serving.
On success the response includes foodId and servingId needed for
log_custom_food. If the API returns no data (204), use
get_custom_foods(search=food_name) to retrieve those IDs.
All nutrient amounts are ABSOLUTE values per serving, not %DV.
Nutrition labels often print %DV for calcium/iron/vitamin D —
convert to absolute units before passing.
Args:
food_name: Name of the custom food (e.g. "Homemade Chocolate Cookies")
calories: Calories per serving
serving_unit: Unit for serving size (e.g. "G", "ML", "OZ"). Default "G"
number_of_units: Serving size in the specified unit. Default 100
brand_name: Brand or vendor name (e.g. "Three Bridges")
carbs: Carbohydrates in grams per serving
protein: Protein in grams per serving
fat: Total fat in grams per serving
fiber: Fiber in grams per serving
sugar: Sugar in grams per serving
saturated_fat: Saturated fat in grams per serving
sodium: Sodium in mg per serving
cholesterol: Cholesterol in mg per serving
potassium: Potassium in mg per serving
trans_fat: Trans fat in grams per serving
calcium: Calcium in mg per serving (NOT %DV)
iron: Iron in mg per serving (NOT %DV)
vitamin_d: Vitamin D in mcg per serving (NOT %DV)
|
| update_custom_foodA | Update an existing custom food in the user's Garmin nutrition library Fetches the food's current record (by food_id, so renaming is safe)
before writing so that omitted optional fields (brand, carbs, protein,
fat, micros, etc.) preserve their existing values rather than being
cleared. Only the fields you explicitly pass are changed; everything
else is carried forward from the current record.
Garmin replaces the whole record on update. If the current record
cannot be read, the update is refused unless serving_unit and
number_of_units are given; the call then replaces the record in full,
and any brand or nutrient you omit is cleared.
Only future logs see the change. Each food-log entry stores its own
copy of the food's nutrition from when it was logged, so entries
already logged, and those days' summaries, keep the old values. To
correct a past day, delete_food_log each affected entry and log it
again after the update.
All nutrient amounts are ABSOLUTE values per serving, not %DV.
Nutrition labels often print %DV for calcium/iron/vitamin D —
convert to absolute units before passing.
Use get_custom_foods first to find the foodId and servingId.
Args:
food_id: ID of the custom food to update (from get_custom_foods)
serving_id: Serving ID of the food (from get_custom_foods)
food_name: Name of the custom food
calories: Calories per serving
serving_unit: Unit for serving size (e.g. "G", "ML", "OZ");
omit to preserve the existing value
number_of_units: Serving size in the specified unit;
omit to preserve the existing value
brand_name: Brand or vendor name; omit to preserve the existing value
carbs: Carbohydrates in grams per serving
protein: Protein in grams per serving
fat: Total fat in grams per serving
fiber: Fiber in grams per serving
sugar: Sugar in grams per serving
saturated_fat: Saturated fat in grams per serving
sodium: Sodium in mg per serving
cholesterol: Cholesterol in mg per serving
potassium: Potassium in mg per serving
trans_fat: Trans fat in grams per serving
calcium: Calcium in mg per serving (NOT %DV)
iron: Iron in mg per serving (NOT %DV)
vitamin_d: Vitamin D in mcg per serving (NOT %DV)
|
| delete_custom_foodA | Delete a custom food from the user's Garmin nutrition library Permanently removes a custom food entry — this cannot be undone and
the deleted food's name/brand/nutrition data cannot be recovered from
the API afterward. The default call previews the food without deleting
it. Review that preview, then call again with confirm=true.
Deleting a food does NOT require it to be unreferenced: existing food
log entries that already reference this food are NOT blocked or
removed — they remain in the log (their nutrition still counts toward
daily totals) but are marked inactive (foodInactive: true) and can no
longer be edited/re-logged from the library.
Use get_custom_foods to find the foodId, and match on the exact
foodId (not just a name search) — Garmin's search can return loosely
related results for a given search term, not just exact matches.
Args:
food_id: ID of the custom food to delete — a 32-char hex string
(from get_custom_foods or create_custom_food)
confirm: Set true to delete after reviewing the default preview
|
| log_custom_foodA | Log a food item to a meal on a date Adds a food entry to the nutrition log. The meal is determined
automatically by matching meal_time against each meal's
startTime/endTime window; falls back to SNACKS if no window matches.
Food sources:
- "GARMIN" (default): user's custom food library. Use
get_custom_foods to find food_id and serving_id.
- "FATSECRET": branded/catalog food from FatSecret. Use
search_foods to find food_id and serving_id. Pass the source
value from the search_foods result (e.g. "FATSECRET").
Garmin custom food IDs are 32-char hex UUIDs; FatSecret IDs are
numeric strings (e.g. "4132350"). Passing the wrong source for a
given food_id returns a 400 from Garmin.
Args:
meal_date: Date in YYYY-MM-DD format
meal_time: Time in HH:MM:SS format (e.g. "12:30:00", account timezone)
food_id: Food ID from get_custom_foods (GARMIN) or search_foods (FATSECRET)
serving_id: Serving ID from get_custom_foods or search_foods
serving_qty: Number of servings (default 1)
source: Food namespace — "GARMIN" (default) or "FATSECRET"
|
| log_foodA | Quick-add a food entry with macro values to the nutrition log Logs food directly by name and macros without requiring a food ID.
Uses Garmin's Quick Add feature. The meal is determined automatically
by matching meal_time against each meal's startTime/endTime window;
falls back to SNACKS if no window matches.
Args:
meal_date: Date in YYYY-MM-DD format
name: Display name for the food entry
calories: Calories (kcal)
carbs: Carbohydrates in grams
protein: Protein in grams
fat: Fat in grams
meal_time: Time in HH:MM:SS format (account timezone)
|
| delete_food_logA | Delete a food log entry Permanently removes a logged food item from the nutrition log.
Works for both QUICK_ADD and REGULAR_LOG entry types.
Use get_nutrition_daily_food_log to find the logId and date. The default
call previews the matching entry; call again with confirm=true to delete.
Args:
log_id: Log entry ID to delete — a 32-char hex UUID
(from get_nutrition_daily_food_log)
meal_date: Date of the log entry in YYYY-MM-DD format
confirm: Set true to delete after reviewing the default preview
|
| upsert_and_logA | Find-or-create a custom food then log it in one step Searches the user's custom food library for food_name. If found, logs
it immediately. If not found, creates it with the provided nutrition
data and then logs it. This avoids duplicate food entries and removes
the need for separate search → create → log round-trips.
Matching is by food_name alone (case-insensitive) — brand_name never
affects find-or-create lookup, so it can't cause a duplicate by missing
an existing unbranded record. If an existing match is found, it is
logged as stored, using its first serving: calories, carbs, protein,
fat, brand_name, serving_unit and number_of_units are all ignored and
the stored food is not changed; only serving_qty applies. Those values
only take effect when creating a new food. To change an existing
food's nutrition, serving size or brand, use update_custom_food.
On an error after creation, custom_food_created is true and
write_committed describes the food log, not the library food. A failed
or exhausted lookup never triggers another create automatically.
Args:
meal_date: Date in YYYY-MM-DD format
meal_time: Time in HH:MM:SS format (account timezone); used to
determine the meal automatically
food_name: Name of the food to find or create
calories: Calories per serving (new food only)
carbs: Carbohydrates in grams per serving (new food only)
protein: Protein in grams per serving (new food only)
fat: Total fat in grams per serving (new food only)
brand_name: Brand or vendor name (new food only)
serving_unit: Unit for serving size (e.g. "G", "ML", "OZ"). Default "G"
(new food only)
number_of_units: Serving size in the specified unit. Default 100
(new food only)
serving_qty: Number of servings to log (default 1)
|
| create_walk_run_workoutA | Create a walk/run interval workout and upload it to Garmin Connect. Builds the internal Garmin JSON automatically and returns the new workout ID.
Args:
name: Workout name (e.g. "W3 Mié 2:2")
Max 256 characters: Garmin SILENTLY TRUNCATES longer names.
run_seconds: Duration of each run interval in seconds
walk_seconds: Duration of each walk/recovery interval in seconds
repeats: Number of run/walk repetitions
warmup_min: Warmup duration in minutes
cooldown_min: Cooldown duration in minutes
hr_zone: Target heart-rate zone (Z1-Z5, default Z3)
|
| create_run_workoutA | Create a continuous run workout and upload it to Garmin Connect. Builds a single uninterrupted run interval with warmup and cooldown walks.
Targets a named Garmin heart-rate zone by default. Named zones (Z1-Z5)
don't line up with every real training target -- e.g. a 136-148 bpm
Zone 2 goal straddles Garmin's Z2 (118-137) and Z3 (138-157). Pass
hr_min and hr_max together to target that exact bpm range instead;
the watch will then show "in range" only for the range you actually
want, not a whole zone that over- or under-shoots it.
Args:
name: Workout name (e.g. "Step 8 - 30min continuous")
Max 256 characters: Garmin SILENTLY TRUNCATES longer names.
run_seconds: Duration of the run in seconds
warmup_min: Warmup walk duration in minutes
cooldown_min: Cooldown walk duration in minutes
hr_zone: Target heart-rate zone (Z1-Z5, default Z3). Ignored if hr_min/hr_max are given.
hr_min: Optional custom target heart rate range, minimum bpm (must be given with hr_max)
hr_max: Optional custom target heart rate range, maximum bpm (must be given with hr_min)
|
| create_run_interval_workoutA | Create a repeat-based interval run workout and upload it to Garmin Connect. Builds warmup -> repeats x [work interval + jog recovery] -> cooldown. Use this
instead of create_run_workout whenever the session has more than one work
interval (threshold reps, VO2 intervals, cruise intervals, strides).
Work intervals target a named heart-rate zone by default, but named zones are
usually far too wide for interval work: a threshold session at 172-180 bpm sits
inside a Z3 that may span 158-184. Pass hr_min and hr_max together to target the
exact bpm range, so the watch alerts as soon as the effort drifts off target.
Recovery steps carry no target unless recovery_hr_min/max are given -- a capped
recovery alerts constantly right after a hard rep, since heart rate lags effort.
Recovery HR bounds require recovery_seconds > 0.
Example -- 3 x 6 min at HR 172-180 with 3 min jogs, 12m warmup, 8m cooldown:
repeats=3, rep_seconds=360, recovery_seconds=180,
hr_min=172, hr_max=180, warmup_min=12, cooldown_min=8
Args:
name: Workout name (e.g. "Threshold 3x6min")
repeats: Number of work intervals
rep_seconds: Duration of each work interval in seconds
recovery_seconds: Jog recovery between work intervals in seconds (0 to omit)
warmup_min: Warmup duration in minutes
cooldown_min: Cooldown duration in minutes
hr_zone: Target zone for the work intervals (Z1-Z5, default Z4). Ignored if hr_min/hr_max are given.
hr_min: Custom target HR range for the work intervals, minimum bpm (with hr_max)
hr_max: Custom target HR range for the work intervals, maximum bpm (with hr_min)
recovery_hr_min: Optional HR range for recovery jogs, minimum bpm (with recovery_hr_max)
recovery_hr_max: Optional HR range for recovery jogs, maximum bpm (with recovery_hr_min)
|
| create_z2_walk_workoutA | Create a steady Z2 walking workout and upload it to Garmin Connect. Args:
name: Workout name
Max 256 characters: Garmin SILENTLY TRUNCATES longer names.
duration_min: Main walking block duration in minutes
hr_min: Minimum heart rate in bpm (used for description; target is Z2)
hr_max: Maximum heart rate in bpm (used for description; target is Z2)
|
| create_strength_workoutA | Create a strength workout and upload it to Garmin Connect. Each exercise becomes a reps-based step; when sets > 1 the exercise is
emitted as a repeat group of that many iterations (work + rest per set),
so Garmin shows the real set count. The name is kept in the step
description; it is also sent as exerciseName, which Garmin only retains when
it matches one of its own exercise keys (e.g. "FARMERS_CARRY").
Args:
name: Workout name
Max 256 characters: Garmin SILENTLY TRUNCATES longer names.
exercises: List of dicts with keys: name, sets, reps, rest_seconds and an
optional category. Category is omitted from the payload when not
given; Garmin accepts that. When given it must be one of Garmin's
exercise categories (e.g. SQUAT, DEADLIFT, PUSH_UP, CARRY, SLED) —
anything else, including "UNASSIGNED" and "OTHER", is rejected with
400 Invalid category. Full list:
https://connect.garmin.com/web-data/exercises/Exercises.json
|
| schedule_weekA | Schedule a list of workouts for the week in a single call. Idempotent: if a workout is already scheduled for that date, it is
reported as already scheduled and the POST is skipped (avoids
duplicating calendar entries).
Each entry is handled on its own: an invalid or failing entry is
reported with status "failed" or "error" and the rest still run.
A successful entry includes scheduled_workout_id when Garmin returns
the calendar-entry ID; pass it to unschedule_workout to remove the entry.
Args:
week: List of dicts with keys: date (YYYY-MM-DD), workout_id (int)
|
| get_coursesA | List all courses saved on Garmin Connect. Returns a curated list of courses with id, name, distance, activity type
and creation date. |
| get_course_detailsA | Get full details of a Garmin Connect course by ID. Returns course metadata, elevation gain/loss, total distance,
and all custom course waypoints (shops, water, food, campgrounds, hazards).
Args:
course_id: ID of the course (from get_courses).
|
| download_course_gpxA | Download a Garmin Connect course as a GPX file. The GPX is rebuilt from the course's track points (lat/lon/elevation)
and course points (as waypoints); it is not the originally uploaded file.
Args:
course_id: ID of the course to download.
output_path: Optional destination directory (saved as {course_id}.gpx)
or file path ending in .gpx; any other file path is rejected.
Defaults to the download_activity_file directory
(GARMIN_FIT_DOWNLOAD_DIR, then set_fit_download_dir), else
./courses/{course_id}.gpx.
|
| upload_courseA | Upload a GPX file as a Garmin Connect Course. The course can then be loaded onto the watch (sync or "Send to Device")
and used as a navigation course or to build a PacePro strategy.
Args:
gpx_path: Absolute path to the .gpx file on disk.
course_name: Override the course name. Defaults to the name parsed
from the GPX file. Max 128 characters; Garmin rejects longer.
activity_type: One of running, cycling, hiking, walking, trail_running,
mountain_biking, road_biking, gravel_cycling. Defaults to running.
description: Optional description shown on the course detail page.
Max 512 characters; Garmin rejects longer.
|
| delete_courseA | Delete a course from Garmin Connect. This cannot be undone. Call once with confirm=false (the default) to
preview the course, then call again with confirm=true to delete it.
Args:
course_id: ID of the course to delete (get IDs from get_courses).
confirm: Must be true to actually delete. Default false returns a preview.
|
| get_activity_fit_messagesA | Retrieve and generically parse an activity's original FIT file. This is the source-of-truth endpoint for original device activity data.
It returns every message and every field emitted by the FIT decoder
without applying sport-specific curation. Messages remain in file order,
and each field includes its decoded value plus units and definition
number when available. Unknown and duplicate fields are retained.
Garmin Connect edits made after upload may be stored only in Garmin's
service and are not necessarily written back into the original FIT file.
This tool intentionally does not merge those service-side edits.
High-frequency ``record`` messages are counted but omitted by default.
Other message types occurring more than 100 times are also inventoried
but omitted from an unfiltered default response. Request those types
explicitly with message_types. All returned messages are bounded by
message_offset/message_limit (maximum 5000 per call); follow
pagination.next_offset until absent to retrieve the full selected stream.
Use message_types to return only particular FIT message types while
message_counts still inventories the complete file. For example, a
strength workout can usually be inspected efficiently with
["session", "lap", "set", "exercise_title"]. Message type names are
case-insensitive and should use FIT/fitparse snake_case names.
Args:
activity_id: Garmin activity ID.
message_types: Optional list of FIT message types to return. Omit to
return low-frequency non-record message types.
include_records: Include the high-frequency record stream (default false).
message_offset: Zero-based offset within the selected message stream.
message_limit: Maximum messages returned per call, 1-5000 (default 1000).
|
| get_activity_fit_dataA | Download and parse FIT file for an activity to expose advanced cycling data. Returns data not available through the standard REST API, including:
- DI2 / electronic shifting events with cadence at time of shift, grade at shift,
gear combinations, shift quality classification, and terrain-grouped shift analysis
- Cycling dynamics per session and lap: platform center offset (PCO), left/right power
balance, torque effectiveness, pedal smoothness
- Variability Index (NP / avg_power) per session and lap
- Climb detection with VAM (vertical ascent rate), avg power/cadence/HR per climb,
and W/kg per climb (using the latest Garmin weigh-in on or before the ride,
up to 90 days back; rider_weight_date says which weigh-in was used)
- Grade-correlated stats: avg power, cadence, HR broken down by terrain steepness
- Grade comes from the device's per-record grade field when present; otherwise
it is derived from altitude and distance (~100 m window). grade_source
("device" | "derived") says which
- HR drift / cardiac drift coefficient (aerobic decoupling for rides ≥60 min)
- Temperature correlation: avg HR/power in hottest vs. coolest portions of ride
- Power Duration Curve: best mean maximal power at 5s, 30s, 1min, 5min, 10min, 20min, 60min
- Optional full per-second time series when include_records=True
Multisport files (triathlon, duathlon) contain one session per leg. For
these, the response adds multisport=true and a sessions list with every
leg; session and the record-based analyses (power curve, climbs, grade,
HR drift, temperature) describe one leg only — the cycling leg if there
is exactly one, else the longest — given by analyzed_session_index and
explained in analysis_note. Laps and records still cover all legs.
Shift quality:
- proactive: shifted at 70-100 rpm (ideal cadence range)
- reactive: shifted below 70 rpm (already grinding before shifting)
- coasting: shifted at 0 rpm (mid-stop or freewheeling)
- spun_out: shifted above 100 rpm (waited too long in easy gear)
Note: DI2 data requires Shimano Di2 / SRAM eTap. Cycling dynamics require a
compatible power meter (e.g., Garmin Rally, Favero Assioma, PowerTap P1 pedals).
Args:
activity_id: Garmin activity ID
include_records: Include full per-second time series (default False).
Warning: adds significant data volume for long rides.
|
| get_power_duration_curveA | Get season-best Power Duration Curve across recent activities. Downloads FIT files for recent activities of the requested type and computes best mean maximal
power at each standard duration. Returns season bests with which activity and date
each best came from.
Durations: 5s (sprint), 30s, 1min, 5min (VO2 max proxy), 10min, 20min (FTP proxy), 60min
Use the 20-minute best × 0.95 as a strong FTP estimate without a formal test.
Warning: downloads multiple FIT files — may take 30-60 seconds for 20 activities.
Args:
num_activities: Number of recent activities matching activity_type to request
(default 20, max 50)
activity_type: Activity type to filter (default "cycling")
|
| download_activity_fileA | Download an activity and save it to disk as a file. Saves the activity in the requested format. Defaults to the original .fit
file; Garmin also supports gpx, tcx, and csv.
Directory resolution (first match wins):
1. output_dir argument (one-off; not persisted)
2. GARMIN_FIT_DOWNLOAD_DIR environment variable
3. persisted config (set via set_fit_download_dir)
If none is configured, returns status "needs_setup" with a suggested
default (the server's current working directory). In that case, ask the
user where to save, call set_fit_download_dir(path), then call this tool
again.
Files are named "{activity_id}.{ext}" and overwrite any existing file.
Args:
activity_id: Garmin activity ID
format: One of fit, gpx, tcx, csv (default fit)
output_dir: Optional one-off directory override (not persisted)
|
| set_fit_download_dirA | Set and persist the default directory for downloaded activity files. Stores the absolute path in a small JSON config file
(~/.garminconnect_fit_config.json, overridable via GARMIN_FIT_CONFIG) so
download_activity_file can save files without asking again.
Args:
path: Directory where activity files (.fit/.gpx/.tcx/.csv) are saved.
Pass the current working directory to keep files where the
server runs.
|
| get_calendar_eventsA | Get races and events on the Garmin Connect calendar between two dates Returns calendar entries the user added or subscribed to in Garmin
Connect, such as upcoming races. Use this to answer questions about
which events or races are scheduled.
These entries are not returned by get_scheduled_workouts, which covers
only workouts, nor by get_goals. This is the only tool that exposes
them.
Each event reports its distance in meters when Garmin stores one,
the user's custom goal time in seconds when set, the local start
time when the organiser published it, and two flags: is_race marks
the entry as a race rather than a general event, and primary_event
marks the goal race that an active training plan targets. Goal time
comes from a per-event detail request.
Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
|