← Back to My Google Health Data (Beta) docs
My Google Health Data (Beta) — Tool Reference
Beta: access sleep, exercise, and other Fitbit tracker data via the new Google Health API.
Your AI assistant discovers and invokes these tools through the
MCP Server's meta tools —
it calls execute_tool with the tool name and arguments below.
# detect_anomalies read
Detect unusual Fitbit metric values against a rolling baseline and return coaching-safe anomaly flags with Z-score analysis.
Full description
Detect deviations vs a rolling baseline for selected metrics.
This is non-diagnostic pattern detection for coaching-only language.
Uses Z-score analysis to identify values outside normal range.
Parameters:
metrics (array of strings, required): List of metrics to analyze for anomalies. Valid values:
- "resting_hr": Resting heart rate
- "hrv": Heart rate variability
- "steps": Daily step count
- "sleep_duration": Total sleep hours
- "spo2": Blood oxygen saturation
Example: ["resting_hr", "hrv", "sleep_duration"]
window_days (int, required): Number of days in the analysis window ending at end_date
(typically 7-30). A preceding window of the same length seeds the rolling baseline.
end_date (str, required): End date of analysis window in format YYYY-MM-DD (e.g., "2025-11-10")
sensitivity (str, optional): Detection sensitivity. Valid values:
- "low": Only flag extreme outliers (>3 std deviations)
- "medium": Flag significant deviations (>2 std deviations)
- "high": Flag any unusual values (>1.5 std deviations)
Default: "medium"
min_confirmed_days (int, optional): Minimum days of data required for reliable detection (2-7). Default: 2
data_source_family (str, optional): Google Health source-family selector. Use "google-wearables"
to detect anomalies from tracker/wearable data. This is not exact paired-device selection.
Returns:
DetectAnomaliesResult with:
- anomalies: Array of detected anomaly objects with:
- metric: Which metric showed the anomaly
- start_date: First date in anomalous span
- end_date: Last date in anomalous span
- z_score: How many standard deviations from mean at the anomaly span's end date
- direction: "up" or "down" (above or below baseline)
- rationale: Human-readable explanation of the anomaly
Example:
Detect heart rate anomalies in last 14 days with medium sensitivity:
{"metrics": ["resting_hr", "hrv"], "window_days": 14, "end_date": "2025-11-10", "sensitivity": "medium"}
Detect tracker-source anomalies:
{"metrics": ["resting_hr", "hrv"], "window_days": 14, "end_date": "2026-06-17", "data_source_family": "google-wearables"}
Notes:
- Returns empty array if no anomalies detected (this is normal)
- Returned anomaly spans are bounded to [end_date - window_days + 1, end_date]
- Requires at least min_confirmed_days consecutive anomalous values
- NOT for medical diagnosis - coaching/wellness insights only
Errors:
UNAUTHORIZED: Could not authenticate
VALIDATION_ERROR: Invalid metric name or sensitivity value
DATA_GAP: Insufficient data for anomaly detection | Parameter | Type | Required | Description |
|---|---|---|---|
metrics | array<"resting_hr" | "hrv" | "sleep_efficiency" | "sleep_duration" | "spo2" | "steps"> | Yes | Metrics to check for anomalies |
window_days | integer | No | Number of days in the analysis window ending at end_date Default: 14 |
end_date | string | Yes | End date (YYYY-MM-DD) |
sensitivity | "low" | "medium" | "high" | No | Detection sensitivity Default: "medium" |
min_confirmed_days | integer | No | Minimum consecutive days Default: 2 |
data_source_family | "default" | "all-sources" | "google-wearables" | "google-sources" | No | Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection. Default: "default" |
Parameter schema (JSON)
{
"description": "Parameters for detect_anomalies",
"properties": {
"metrics": {
"description": "Metrics to check for anomalies",
"items": {
"enum": [
"resting_hr",
"hrv",
"sleep_efficiency",
"sleep_duration",
"spo2",
"steps"
],
"type": "string"
},
"title": "Metrics",
"type": "array"
},
"window_days": {
"default": 14,
"description": "Number of days in the analysis window ending at end_date",
"minimum": 7,
"title": "Window Days",
"type": "integer"
},
"end_date": {
"description": "End date (YYYY-MM-DD)",
"title": "End Date",
"type": "string"
},
"sensitivity": {
"default": "medium",
"description": "Detection sensitivity",
"enum": [
"low",
"medium",
"high"
],
"title": "Sensitivity",
"type": "string"
},
"min_confirmed_days": {
"default": 2,
"description": "Minimum consecutive days",
"minimum": 1,
"title": "Min Confirmed Days",
"type": "integer"
},
"data_source_family": {
"default": "default",
"description": "Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection.",
"enum": [
"default",
"all-sources",
"google-wearables",
"google-sources"
],
"title": "Data Source Family",
"type": "string"
}
},
"required": [
"metrics",
"end_date"
],
"title": "DetectAnomaliesParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"Anomaly": {
"description": "Detected anomaly",
"properties": {
"metric": {
"title": "Metric",
"type": "string"
},
"start_date": {
"title": "Start Date",
"type": "string"
},
"end_date": {
"title": "End Date",
"type": "string"
},
"z_score": {
"title": "Z Score",
"type": "number"
},
"direction": {
"enum": [
"up",
"down"
],
"title": "Direction",
"type": "string"
},
"rationale": {
"title": "Rationale",
"type": "string"
}
},
"required": [
"metric",
"start_date",
"end_date",
"z_score",
"direction",
"rationale"
],
"title": "Anomaly",
"type": "object"
}
},
"description": "Result from detect_anomalies",
"properties": {
"anomalies": {
"items": {
"$ref": "#/$defs/Anomaly"
},
"title": "Anomalies",
"type": "array"
}
},
"required": [
"anomalies"
],
"title": "DetectAnomaliesResult",
"type": "object"
} # get_active_zone_minutes read
Fetch Google Health Active Zone Minutes by day with fat-burn, cardio, peak, and weekly totals.
Full description
Fetch Google Health Active Zone Minutes over a date range. Returns daily total Active Zone Minutes with fat-burn, cardio, and peak breakdowns plus weekly totals clipped to the requested range.
| Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Inclusive start date (YYYY-MM-DD) |
end_date | string | Yes | Inclusive end date (YYYY-MM-DD) |
data_source_family | "default" | "all-sources" | "google-wearables" | "google-sources" | No | Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection. Default: "default" |
Parameter schema (JSON)
{
"description": "Parameters for get_active_zone_minutes",
"properties": {
"start_date": {
"description": "Inclusive start date (YYYY-MM-DD)",
"title": "Start Date",
"type": "string"
},
"end_date": {
"description": "Inclusive end date (YYYY-MM-DD)",
"title": "End Date",
"type": "string"
},
"data_source_family": {
"default": "default",
"description": "Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection.",
"enum": [
"default",
"all-sources",
"google-wearables",
"google-sources"
],
"title": "Data Source Family",
"type": "string"
}
},
"required": [
"start_date",
"end_date"
],
"title": "ActiveZoneMinutesParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"ActiveZoneMinutesBreakdown": {
"description": "Active Zone Minutes by zone.",
"properties": {
"fat_burn_minutes": {
"default": 0,
"title": "Fat Burn Minutes",
"type": "integer"
},
"cardio_minutes": {
"default": 0,
"title": "Cardio Minutes",
"type": "integer"
},
"peak_minutes": {
"default": 0,
"title": "Peak Minutes",
"type": "integer"
}
},
"title": "ActiveZoneMinutesBreakdown",
"type": "object"
},
"ActiveZoneMinutesDay": {
"description": "One day's Active Zone Minutes.",
"properties": {
"date": {
"title": "Date",
"type": "string"
},
"total_minutes": {
"title": "Total Minutes",
"type": "integer"
},
"zones": {
"$ref": "#/$defs/ActiveZoneMinutesBreakdown"
}
},
"required": [
"date",
"total_minutes",
"zones"
],
"title": "ActiveZoneMinutesDay",
"type": "object"
},
"ActiveZoneMinutesWeek": {
"description": "Weekly Active Zone Minutes total clipped to the requested date range.",
"properties": {
"week_start": {
"title": "Week Start",
"type": "string"
},
"week_end": {
"title": "Week End",
"type": "string"
},
"total_minutes": {
"title": "Total Minutes",
"type": "integer"
},
"zones": {
"$ref": "#/$defs/ActiveZoneMinutesBreakdown"
}
},
"required": [
"week_start",
"week_end",
"total_minutes",
"zones"
],
"title": "ActiveZoneMinutesWeek",
"type": "object"
}
},
"description": "Result from get_active_zone_minutes",
"properties": {
"days": {
"items": {
"$ref": "#/$defs/ActiveZoneMinutesDay"
},
"title": "Days",
"type": "array"
},
"weekly_totals": {
"items": {
"$ref": "#/$defs/ActiveZoneMinutesWeek"
},
"title": "Weekly Totals",
"type": "array"
},
"notes": {
"items": {
"type": "string"
},
"title": "Notes",
"type": "array"
}
},
"required": [
"days",
"weekly_totals"
],
"title": "GetActiveZoneMinutesResult",
"type": "object"
} # get_breathing_rate read
Fetch Fitbit per-stage overnight breathing rate for a date range with optional rolling baseline + Z-score.
Full description
Per-night breathing rate, broken out by sleep stage, for a date range.
Returns four breathing rates per night (full / deep / REM / light) because
different stages have different baselines (REM is typically higher than
deep). When `with_baseline=true`, fetches the preceding `baseline_days`
window and emits per-night `delta_vs_baseline` plus `z_score` against the
full-sleep rate.
Parameters:
start_date (str, required): Inclusive start date (YYYY-MM-DD).
end_date (str, required): Inclusive end date (YYYY-MM-DD). Max 30 days.
with_baseline (bool, optional): Include rolling baseline + per-night z. Default true.
baseline_days (int, optional): Window size for the baseline (7-90). Default 28.
data_source_family (str, optional): Google Health source-family selector. Use "google-wearables"
to query tracker/wearable breathing-rate data. This is not exact paired-device selection.
Returns:
GetBreathingRateResult with `nights`, `baseline`, `missing_dates`, `notes`.
Notes:
- Requires the `respiratory_rate` Fitbit OAuth scope (added in 2026-04;
existing connected users may need to re-authorize).
- Fitbit's API uses -1.0 as a null sentinel when a stage didn't have
enough data; this is converted to actual `null` before returning.
- Only nights with >=3h of quality sleep are returned by Fitbit; short
or fragmented nights will appear in `missing_dates`.
- Clinical sensitivity is low (~±1 breath/min during illness), so
z-scores are more useful than raw deltas.
- Tracker-source example:
{"start_date": "2026-06-17", "end_date": "2026-06-17", "data_source_family": "google-wearables"}
Errors:
UNAUTHORIZED: User has not connected Fitbit or token is invalid/expired.
INSUFFICIENT_SCOPE: 'respiratory_rate' scope not granted.
VALIDATION_ERROR: Invalid date range (start > end, or > 30 days). | Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Inclusive start date (YYYY-MM-DD) |
end_date | string | Yes | Inclusive end date (YYYY-MM-DD); range max 30 days |
with_baseline | boolean | No | If true, fetch a preceding `baseline_days` window and emit per-night delta + Z-score against full-sleep rate. Default: true |
baseline_days | integer | No | Days of preceding history to use for the rolling baseline (7-90). Default: 28 |
data_source_family | "default" | "all-sources" | "google-wearables" | "google-sources" | No | Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection. Default: "default" |
Parameter schema (JSON)
{
"description": "Parameters for get_breathing_rate",
"properties": {
"start_date": {
"description": "Inclusive start date (YYYY-MM-DD)",
"title": "Start Date",
"type": "string"
},
"end_date": {
"description": "Inclusive end date (YYYY-MM-DD); range max 30 days",
"title": "End Date",
"type": "string"
},
"with_baseline": {
"default": true,
"description": "If true, fetch a preceding `baseline_days` window and emit per-night delta + Z-score against full-sleep rate.",
"title": "With Baseline",
"type": "boolean"
},
"baseline_days": {
"default": 28,
"description": "Days of preceding history to use for the rolling baseline (7-90).",
"maximum": 90,
"minimum": 7,
"title": "Baseline Days",
"type": "integer"
},
"data_source_family": {
"default": "default",
"description": "Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection.",
"enum": [
"default",
"all-sources",
"google-wearables",
"google-sources"
],
"title": "Data Source Family",
"type": "string"
}
},
"required": [
"start_date",
"end_date"
],
"title": "GetBreathingRateParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"BreathingRateBaseline": {
"description": "Rolling baseline of full-sleep breathing rate.",
"properties": {
"mean_full_sleep_rate": {
"title": "Mean Full Sleep Rate",
"type": "number"
},
"stdev_full_sleep_rate": {
"title": "Stdev Full Sleep Rate",
"type": "number"
},
"n_nights_in_baseline": {
"title": "N Nights In Baseline",
"type": "integer"
},
"window_days": {
"title": "Window Days",
"type": "integer"
}
},
"required": [
"mean_full_sleep_rate",
"stdev_full_sleep_rate",
"n_nights_in_baseline",
"window_days"
],
"title": "BreathingRateBaseline",
"type": "object"
},
"BreathingRateNight": {
"description": "One night of breathing-rate data, broken out by sleep stage. Stage rates differ\nmeaningfully (REM is typically higher than deep); returning all four preserves that signal.",
"properties": {
"date": {
"description": "Fitbit's dateTime; date the measurement ended",
"title": "Date",
"type": "string"
},
"full_sleep_rate": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Avg breaths/min across full sleep",
"title": "Full Sleep Rate"
},
"deep_sleep_rate": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Avg during deep sleep (cleanest signal)",
"title": "Deep Sleep Rate"
},
"rem_sleep_rate": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Rem Sleep Rate"
},
"light_sleep_rate": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Light Sleep Rate"
},
"delta_vs_baseline": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "full_sleep_rate minus baseline mean; only with baseline established",
"title": "Delta Vs Baseline"
},
"z_score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "(full_sleep_rate - mean) / stdev; only with baseline established",
"title": "Z Score"
},
"source": {
"anyOf": [
{
"$ref": "#/$defs/RecordSource"
},
{
"type": "null"
}
],
"default": null,
"description": "Best-effort Google Health source metadata"
}
},
"required": [
"date"
],
"title": "BreathingRateNight",
"type": "object"
},
"RecordSource": {
"description": "Best-effort source metadata for a Google Health session record.",
"properties": {
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Google Health dataSource.type, e.g. DEVICE or USER_INPUT",
"title": "Type"
},
"application_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source application name when reported",
"title": "Application Name"
},
"application_package_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source application package when reported",
"title": "Application Package Name"
},
"device_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device model when reported",
"title": "Device Model"
},
"device_manufacturer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device manufacturer when reported",
"title": "Device Manufacturer"
},
"device_uid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable device identifier when reported",
"title": "Device Uid"
},
"device_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device type/category when reported",
"title": "Device Type"
}
},
"title": "RecordSource",
"type": "object"
}
},
"description": "Result from get_breathing_rate",
"properties": {
"nights": {
"items": {
"$ref": "#/$defs/BreathingRateNight"
},
"title": "Nights",
"type": "array"
},
"baseline": {
"anyOf": [
{
"$ref": "#/$defs/BreathingRateBaseline"
},
{
"type": "null"
}
],
"default": null,
"description": "Null when with_baseline=false or fewer than 7 baseline nights present"
},
"missing_dates": {
"items": {
"type": "string"
},
"title": "Missing Dates",
"type": "array"
},
"notes": {
"items": {
"type": "string"
},
"title": "Notes",
"type": "array"
}
},
"required": [
"nights",
"missing_dates",
"notes"
],
"title": "GetBreathingRateResult",
"type": "object"
} # get_cardio_fitness read
Fetch Google Health VO2 max/cardio fitness readings over a date range, including estimated and GPS-run-based sources.
Full description
Fetch Google Health VO2 max/cardio fitness readings over a date range. Returns daily estimated VO2 max readings when available, lower-level VO2 estimate samples when present, and GPS/run-based VO2 max readings from `run-vo2-max`. This is descriptive wellness data, not a diagnosis.
| Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Inclusive start date (YYYY-MM-DD) |
end_date | string | Yes | Inclusive end date (YYYY-MM-DD) |
include_prior_period | boolean | No | If true, include a simple current-vs-prior-period VO2 max trend. Default: true |
data_source_family | "default" | "all-sources" | "google-wearables" | "google-sources" | No | Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection. Default: "default" |
Parameter schema (JSON)
{
"description": "Parameters for get_cardio_fitness",
"properties": {
"start_date": {
"description": "Inclusive start date (YYYY-MM-DD)",
"title": "Start Date",
"type": "string"
},
"end_date": {
"description": "Inclusive end date (YYYY-MM-DD)",
"title": "End Date",
"type": "string"
},
"include_prior_period": {
"default": true,
"description": "If true, include a simple current-vs-prior-period VO2 max trend.",
"title": "Include Prior Period",
"type": "boolean"
},
"data_source_family": {
"default": "default",
"description": "Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection.",
"enum": [
"default",
"all-sources",
"google-wearables",
"google-sources"
],
"title": "Data Source Family",
"type": "string"
}
},
"required": [
"start_date",
"end_date"
],
"title": "CardioFitnessParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"CardioFitnessReading": {
"description": "One Google Health VO2 max reading.",
"properties": {
"date": {
"title": "Date",
"type": "string"
},
"vo2_max": {
"description": "VO2 max in ml/kg/min",
"title": "Vo2 Max",
"type": "number"
},
"source": {
"description": "Source data type: daily estimate, estimate sample, or GPS/run-based reading",
"enum": [
"daily_estimated",
"estimated",
"run_gps"
],
"title": "Source",
"type": "string"
},
"start_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Run/session start time when reported",
"title": "Start Time"
},
"end_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Run/session end time when reported",
"title": "End Time"
},
"source_record": {
"anyOf": [
{
"$ref": "#/$defs/RecordSource"
},
{
"type": "null"
}
],
"default": null,
"description": "Best-effort Google Health source metadata"
}
},
"required": [
"date",
"vo2_max",
"source"
],
"title": "CardioFitnessReading",
"type": "object"
},
"CardioFitnessTrend": {
"description": "Current-vs-prior VO2 max summary.",
"properties": {
"current_mean": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Current Mean"
},
"prior_mean": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Prior Mean"
},
"change_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Change Pct"
}
},
"title": "CardioFitnessTrend",
"type": "object"
},
"RecordSource": {
"description": "Best-effort source metadata for a Google Health session record.",
"properties": {
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Google Health dataSource.type, e.g. DEVICE or USER_INPUT",
"title": "Type"
},
"application_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source application name when reported",
"title": "Application Name"
},
"application_package_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source application package when reported",
"title": "Application Package Name"
},
"device_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device model when reported",
"title": "Device Model"
},
"device_manufacturer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device manufacturer when reported",
"title": "Device Manufacturer"
},
"device_uid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable device identifier when reported",
"title": "Device Uid"
},
"device_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device type/category when reported",
"title": "Device Type"
}
},
"title": "RecordSource",
"type": "object"
}
},
"description": "Result from get_cardio_fitness",
"properties": {
"readings": {
"items": {
"$ref": "#/$defs/CardioFitnessReading"
},
"title": "Readings",
"type": "array"
},
"trend": {
"anyOf": [
{
"$ref": "#/$defs/CardioFitnessTrend"
},
{
"type": "null"
}
],
"default": null
},
"notes": {
"items": {
"type": "string"
},
"title": "Notes",
"type": "array"
}
},
"required": [
"readings"
],
"title": "GetCardioFitnessResult",
"type": "object"
} # get_daily_summary read
Fetch daily Fitbit aggregates for a date range and return per-day metrics with optional personal baselines.
Full description
Fetch per-day aggregates for a date range, optionally including baselines.
Typical uses:
- Daily brief generation (sleep, RHR, HRV, steps)
- Inputs to trend and anomaly detection
- Clinician-style overviews
Parameters:
start_date (str, required): Start date in format YYYY-MM-DD (e.g., "2025-11-01"). Must be <= end_date.
end_date (str, required): End date in format YYYY-MM-DD (e.g., "2025-11-07"). Must be >= start_date.
metrics (array of strings, required): List of metrics to retrieve. Valid values are:
- "steps": Daily step count
- "activity_minutes": Total active minutes (fairly active + very active)
- "active_zone_minutes": Fitbit/Google Active Zone Minutes
- "calories": Calories burned
- "resting_hr": Resting heart rate in bpm
- "hrv": Heart rate variability (RMSSD in ms)
- "sleep": Sleep data (duration, efficiency, REM, deep sleep)
- "spo2": Blood oxygen saturation percentage
- "vo2_max": Daily VO2 max estimate in ml/kg/min
Example: ["steps", "resting_hr", "sleep"]
include_baseline (boolean, optional): Whether to calculate baseline statistics. Default: true
baseline_window_days (integer, optional): Number of days for baseline calculation (min 7). Default: 14
data_source_family (str, optional): Google Health source-family selector. Default "default"
preserves current canonical behavior. Use "google-wearables" to answer requests like
"show data from my tracker" or "use my Fitbit tracker data"; it maps to Google Health
tracker/wearable sources while keeping Google's canonical/deduped reads where supported.
This is not exact paired-device selection.
Returns:
GetDailySummaryResult with:
- days: Array of daily data objects (days with no data are omitted)
- baseline: Optional baseline statistics (mean, stddev) if include_baseline=true
Notes:
- Dates are aligned to the user's Fitbit-configured timezone
- Tracker-source example:
{"start_date": "2026-06-17", "end_date": "2026-06-17", "metrics": ["steps"], "data_source_family": "google-wearables"}
Errors:
UNAUTHORIZED: Could not authenticate or extract user_id from token
INSUFFICIENT_SCOPE: A requested metric requires a scope not granted by user
DATA_GAP: No data available for requested dates (returns empty days array)
VALIDATION_ERROR: Invalid date range (start_date > end_date) or invalid metric name | Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Inclusive start date (YYYY-MM-DD) |
end_date | string | Yes | Inclusive end date (YYYY-MM-DD) |
metrics | array<"steps" | "activity_minutes" | "active_zone_minutes" | "calories" | "resting_hr" | "hrv" | "sleep" | "spo2" | "vo2_max"> | Yes | Metrics to retrieve |
include_baseline | boolean | No | Include baseline calculations Default: true |
baseline_window_days | integer | No | Days for baseline window Default: 14 |
data_source_family | "default" | "all-sources" | "google-wearables" | "google-sources" | No | Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection. Default: "default" |
Parameter schema (JSON)
{
"description": "Parameters for get_daily_summary",
"properties": {
"start_date": {
"description": "Inclusive start date (YYYY-MM-DD)",
"title": "Start Date",
"type": "string"
},
"end_date": {
"description": "Inclusive end date (YYYY-MM-DD)",
"title": "End Date",
"type": "string"
},
"metrics": {
"description": "Metrics to retrieve",
"items": {
"enum": [
"steps",
"activity_minutes",
"active_zone_minutes",
"calories",
"resting_hr",
"hrv",
"sleep",
"spo2",
"vo2_max"
],
"type": "string"
},
"title": "Metrics",
"type": "array"
},
"include_baseline": {
"default": true,
"description": "Include baseline calculations",
"title": "Include Baseline",
"type": "boolean"
},
"baseline_window_days": {
"default": 14,
"description": "Days for baseline window",
"minimum": 7,
"title": "Baseline Window Days",
"type": "integer"
},
"data_source_family": {
"default": "default",
"description": "Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection.",
"enum": [
"default",
"all-sources",
"google-wearables",
"google-sources"
],
"title": "Data Source Family",
"type": "string"
}
},
"required": [
"start_date",
"end_date",
"metrics"
],
"title": "GetDailySummaryParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"Baseline": {
"description": "Baseline statistics",
"properties": {
"window_days": {
"title": "Window Days",
"type": "integer"
},
"metrics": {
"additionalProperties": {
"type": "number"
},
"title": "Metrics",
"type": "object"
}
},
"required": [
"window_days",
"metrics"
],
"title": "Baseline",
"type": "object"
},
"Day": {
"description": "Daily summary data",
"properties": {
"date": {
"title": "Date",
"type": "string"
},
"steps": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Steps"
},
"activity_minutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Activity Minutes"
},
"active_zone_minutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Active Zone Minutes"
},
"calories": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Calories"
},
"resting_hr": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Resting Hr"
},
"hrv_rmssd_ms": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Hrv Rmssd Ms"
},
"sleep": {
"anyOf": [
{
"$ref": "#/$defs/DaySleep"
},
{
"type": "null"
}
],
"default": null
},
"spo2_avg_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Spo2 Avg Pct"
},
"vo2_max": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "VO2 max estimate in ml/kg/min",
"title": "Vo2 Max"
}
},
"required": [
"date"
],
"title": "Day",
"type": "object"
},
"DaySleep": {
"description": "Sleep data for a single day",
"properties": {
"duration_hours": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Duration Hours"
},
"efficiency_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Efficiency Pct"
},
"latency_min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Latency Min"
},
"waso_min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Waso Min"
},
"rem_hours": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Rem Hours"
},
"deep_hours": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Deep Hours"
}
},
"title": "DaySleep",
"type": "object"
}
},
"description": "Result from get_daily_summary",
"properties": {
"days": {
"items": {
"$ref": "#/$defs/Day"
},
"title": "Days",
"type": "array"
},
"baseline": {
"anyOf": [
{
"$ref": "#/$defs/Baseline"
},
{
"type": "null"
}
],
"default": null
},
"warnings": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "API warnings or errors encountered during data fetch",
"title": "Warnings"
}
},
"required": [
"days"
],
"title": "GetDailySummaryResult",
"type": "object"
} # get_heart_rate_zones read
Fetch Google Health daily heart-rate-zone thresholds, time in zone, and calories by zone.
Full description
Fetch Google Health daily heart-rate-zone data over a date range. Returns daily zone thresholds plus time-in-zone and calories-in-zone breakdowns when those data types are available.
| Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Inclusive start date (YYYY-MM-DD) |
end_date | string | Yes | Inclusive end date (YYYY-MM-DD) |
data_source_family | "default" | "all-sources" | "google-wearables" | "google-sources" | No | Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection. Default: "default" |
Parameter schema (JSON)
{
"description": "Parameters for get_heart_rate_zones",
"properties": {
"start_date": {
"description": "Inclusive start date (YYYY-MM-DD)",
"title": "Start Date",
"type": "string"
},
"end_date": {
"description": "Inclusive end date (YYYY-MM-DD)",
"title": "End Date",
"type": "string"
},
"data_source_family": {
"default": "default",
"description": "Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection.",
"enum": [
"default",
"all-sources",
"google-wearables",
"google-sources"
],
"title": "Data Source Family",
"type": "string"
}
},
"required": [
"start_date",
"end_date"
],
"title": "HeartRateZonesParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"DailyHeartRateZoneThreshold": {
"description": "One daily heart-rate-zone threshold.",
"properties": {
"zone": {
"title": "Zone",
"type": "string"
},
"min_bpm": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Min Bpm"
},
"max_bpm": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Bpm"
}
},
"required": [
"zone"
],
"title": "DailyHeartRateZoneThreshold",
"type": "object"
},
"HeartRateZoneCalories": {
"description": "Daily calories by heart-rate zone.",
"properties": {
"out_of_range_calories": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Out Of Range Calories"
},
"fat_burn_calories": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Fat Burn Calories"
},
"cardio_calories": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Cardio Calories"
},
"peak_calories": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Peak Calories"
}
},
"title": "HeartRateZoneCalories",
"type": "object"
},
"HeartRateZoneMinutes": {
"description": "Daily time in heart-rate zones.",
"properties": {
"out_of_range_minutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Out Of Range Minutes"
},
"fat_burn_minutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Fat Burn Minutes"
},
"cardio_minutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Cardio Minutes"
},
"peak_minutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Peak Minutes"
}
},
"title": "HeartRateZoneMinutes",
"type": "object"
},
"HeartRateZonesDay": {
"description": "One day's daily zone thresholds plus time/calorie breakdowns.",
"properties": {
"date": {
"title": "Date",
"type": "string"
},
"thresholds": {
"items": {
"$ref": "#/$defs/DailyHeartRateZoneThreshold"
},
"title": "Thresholds",
"type": "array"
},
"time_in_zone": {
"anyOf": [
{
"$ref": "#/$defs/HeartRateZoneMinutes"
},
{
"type": "null"
}
],
"default": null
},
"calories_in_zone": {
"anyOf": [
{
"$ref": "#/$defs/HeartRateZoneCalories"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"date"
],
"title": "HeartRateZonesDay",
"type": "object"
}
},
"description": "Result from get_heart_rate_zones",
"properties": {
"days": {
"items": {
"$ref": "#/$defs/HeartRateZonesDay"
},
"title": "Days",
"type": "array"
},
"missing_dates": {
"items": {
"type": "string"
},
"title": "Missing Dates",
"type": "array"
},
"notes": {
"items": {
"type": "string"
},
"title": "Notes",
"type": "array"
}
},
"required": [
"days",
"missing_dates"
],
"title": "GetHeartRateZonesResult",
"type": "object"
} # get_hydration_log read
Fetch Google Health hydration logs over a date range with per-entry amounts and daily water totals.
Full description
Fetch Google Health hydration logs over a date range with per-entry amounts and daily water totals. Hydration logs are user-entered liquid intake records from Google Health. Empty results usually mean the user did not log hydration in the requested range. Missing nutrition access is surfaced as an access error, not an empty result.
| Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Inclusive start date (YYYY-MM-DD) |
end_date | string | Yes | Inclusive end date (YYYY-MM-DD) |
include_daily_totals | boolean | No | Include daily hydration totals Default: true |
data_source_family | "default" | "all-sources" | "google-wearables" | "google-sources" | No | Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection. Default: "default" |
Parameter schema (JSON)
{
"description": "Parameters for get_hydration_log",
"properties": {
"start_date": {
"description": "Inclusive start date (YYYY-MM-DD)",
"title": "Start Date",
"type": "string"
},
"end_date": {
"description": "Inclusive end date (YYYY-MM-DD)",
"title": "End Date",
"type": "string"
},
"include_daily_totals": {
"default": true,
"description": "Include daily hydration totals",
"title": "Include Daily Totals",
"type": "boolean"
},
"data_source_family": {
"default": "default",
"description": "Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection.",
"enum": [
"default",
"all-sources",
"google-wearables",
"google-sources"
],
"title": "Data Source Family",
"type": "string"
}
},
"required": [
"start_date",
"end_date"
],
"title": "HydrationLogParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"HydrationDailyTotal": {
"description": "Daily hydration totals from logged water/liquid entries.",
"properties": {
"date": {
"title": "Date",
"type": "string"
},
"total_milliliters": {
"title": "Total Milliliters",
"type": "number"
},
"total_liters": {
"title": "Total Liters",
"type": "number"
}
},
"required": [
"date",
"total_milliliters",
"total_liters"
],
"title": "HydrationDailyTotal",
"type": "object"
},
"HydrationLogEntry": {
"description": "One Google Health hydration log entry.",
"properties": {
"date": {
"title": "Date",
"type": "string"
},
"start_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Start Time"
},
"end_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "End Time"
},
"milliliters": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Milliliters"
},
"liters": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Liters"
},
"user_provided_unit": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "User Provided Unit"
},
"source_record": {
"anyOf": [
{
"$ref": "#/$defs/RecordSource"
},
{
"type": "null"
}
],
"default": null,
"description": "Best-effort Google Health source metadata"
}
},
"required": [
"date"
],
"title": "HydrationLogEntry",
"type": "object"
},
"RecordSource": {
"description": "Best-effort source metadata for a Google Health session record.",
"properties": {
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Google Health dataSource.type, e.g. DEVICE or USER_INPUT",
"title": "Type"
},
"application_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source application name when reported",
"title": "Application Name"
},
"application_package_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source application package when reported",
"title": "Application Package Name"
},
"device_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device model when reported",
"title": "Device Model"
},
"device_manufacturer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device manufacturer when reported",
"title": "Device Manufacturer"
},
"device_uid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable device identifier when reported",
"title": "Device Uid"
},
"device_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device type/category when reported",
"title": "Device Type"
}
},
"title": "RecordSource",
"type": "object"
}
},
"description": "Result from get_hydration_log",
"properties": {
"entries": {
"items": {
"$ref": "#/$defs/HydrationLogEntry"
},
"title": "Entries",
"type": "array"
},
"daily_totals": {
"items": {
"$ref": "#/$defs/HydrationDailyTotal"
},
"title": "Daily Totals",
"type": "array"
},
"notes": {
"items": {
"type": "string"
},
"title": "Notes",
"type": "array"
}
},
"required": [
"entries"
],
"title": "GetHydrationLogResult",
"type": "object"
} # get_nutrition_log read
Fetch Google Health logged food entries over a date range with calories, macronutrients, and daily totals.
Full description
Fetch Google Health logged food entries over a date range with calories, macronutrients, and daily totals. Nutrition logs are user-entered food records from Google Health. Empty results usually mean the user did not log food in the requested range. Missing nutrition access is surfaced as an access error, not an empty result.
| Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Inclusive start date (YYYY-MM-DD) |
end_date | string | Yes | Inclusive end date (YYYY-MM-DD) |
include_daily_totals | boolean | No | Include daily nutrition totals Default: true |
data_source_family | "default" | "all-sources" | "google-wearables" | "google-sources" | No | Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection. Default: "default" |
Parameter schema (JSON)
{
"description": "Parameters for get_nutrition_log",
"properties": {
"start_date": {
"description": "Inclusive start date (YYYY-MM-DD)",
"title": "Start Date",
"type": "string"
},
"end_date": {
"description": "Inclusive end date (YYYY-MM-DD)",
"title": "End Date",
"type": "string"
},
"include_daily_totals": {
"default": true,
"description": "Include daily nutrition totals",
"title": "Include Daily Totals",
"type": "boolean"
},
"data_source_family": {
"default": "default",
"description": "Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection.",
"enum": [
"default",
"all-sources",
"google-wearables",
"google-sources"
],
"title": "Data Source Family",
"type": "string"
}
},
"required": [
"start_date",
"end_date"
],
"title": "NutritionLogParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"NutritionDailyTotal": {
"description": "Daily nutrition totals from logged food entries.",
"properties": {
"date": {
"title": "Date",
"type": "string"
},
"calories_kcal": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Calories Kcal"
},
"energy_from_fat_kcal": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Energy From Fat Kcal"
},
"carbohydrates_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Carbohydrates G"
},
"fat_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Fat G"
},
"protein_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Protein G"
},
"nutrients_g": {
"additionalProperties": {
"type": "number"
},
"title": "Nutrients G",
"type": "object"
}
},
"required": [
"date"
],
"title": "NutritionDailyTotal",
"type": "object"
},
"NutritionLogEntry": {
"description": "One Google Health nutrition log entry.",
"properties": {
"date": {
"title": "Date",
"type": "string"
},
"start_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Start Time"
},
"end_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "End Time"
},
"food_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Food Name"
},
"food_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Food Id"
},
"meal_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Meal Type"
},
"serving": {
"anyOf": [
{
"$ref": "#/$defs/NutritionServing"
},
{
"type": "null"
}
],
"default": null
},
"calories_kcal": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Calories Kcal"
},
"energy_from_fat_kcal": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Energy From Fat Kcal"
},
"carbohydrates_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Carbohydrates G"
},
"fat_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Fat G"
},
"protein_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Protein G"
},
"nutrients_g": {
"additionalProperties": {
"type": "number"
},
"title": "Nutrients G",
"type": "object"
},
"source_record": {
"anyOf": [
{
"$ref": "#/$defs/RecordSource"
},
{
"type": "null"
}
],
"default": null,
"description": "Best-effort Google Health source metadata"
}
},
"required": [
"date"
],
"title": "NutritionLogEntry",
"type": "object"
},
"NutritionServing": {
"description": "Serving information for a logged food item.",
"properties": {
"amount": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Amount"
},
"unit": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Unit"
},
"unit_display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Unit Display Name"
}
},
"title": "NutritionServing",
"type": "object"
},
"RecordSource": {
"description": "Best-effort source metadata for a Google Health session record.",
"properties": {
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Google Health dataSource.type, e.g. DEVICE or USER_INPUT",
"title": "Type"
},
"application_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source application name when reported",
"title": "Application Name"
},
"application_package_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source application package when reported",
"title": "Application Package Name"
},
"device_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device model when reported",
"title": "Device Model"
},
"device_manufacturer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device manufacturer when reported",
"title": "Device Manufacturer"
},
"device_uid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable device identifier when reported",
"title": "Device Uid"
},
"device_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device type/category when reported",
"title": "Device Type"
}
},
"title": "RecordSource",
"type": "object"
}
},
"description": "Result from get_nutrition_log",
"properties": {
"entries": {
"items": {
"$ref": "#/$defs/NutritionLogEntry"
},
"title": "Entries",
"type": "array"
},
"daily_totals": {
"items": {
"$ref": "#/$defs/NutritionDailyTotal"
},
"title": "Daily Totals",
"type": "array"
},
"notes": {
"items": {
"type": "string"
},
"title": "Notes",
"type": "array"
}
},
"required": [
"entries"
],
"title": "GetNutritionLogResult",
"type": "object"
} # get_overnight_hrv read
Fetch Fitbit overnight HRV (RMSSD) for a date range with optional rolling baseline + Z-score.
Full description
Per-night heart rate variability (RMSSD) for a date range.
Returns the 24-hour RMSSD (the "headline" HRV figure) and the
deep-sleep RMSSD (cleaner signal — less motion artifact, parasympathetic-
dominant). When `with_baseline=true`, additionally fetches the preceding
`baseline_days` window to compute a rolling mean/stdev and emits per-night
`delta_vs_baseline` plus `z_score`.
Parameters:
start_date (str, required): Inclusive start date (YYYY-MM-DD).
end_date (str, required): Inclusive end date (YYYY-MM-DD). Max 30 days.
with_baseline (bool, optional): Include rolling baseline + per-night z. Default true.
baseline_days (int, optional): Window size for the baseline (7-90). Default 28.
data_source_family (str, optional): Google Health source-family selector. Use "google-wearables"
to query tracker/wearable HRV data. This is not exact paired-device selection.
Returns:
GetOvernightHrvResult with `nights`, `baseline`, `missing_dates`, `notes`.
Notes:
- HRV is bundled under the `heartrate` Fitbit OAuth scope, NOT a
separate `hrv` scope.
- Fitbit's `dateTime` is the date the measurement ended; the actual
sleep period began the previous night. Preserved as-is to stay
consistent with `get_sleep_detail`.
- Baseline requires >=7 nights of data; with fewer, `baseline` is
null and per-night Z-scores are omitted.
- Tracker-source example:
{"start_date": "2026-06-17", "end_date": "2026-06-17", "data_source_family": "google-wearables"}
Errors:
UNAUTHORIZED: User has not connected Fitbit or token is invalid/expired.
INSUFFICIENT_SCOPE: 'heartrate' scope not granted.
VALIDATION_ERROR: Invalid date range (start > end, or > 30 days). | Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Inclusive start date (YYYY-MM-DD) |
end_date | string | Yes | Inclusive end date (YYYY-MM-DD); range max 30 days |
with_baseline | boolean | No | If true, fetch a preceding `baseline_days` window and emit per-night delta + Z-score against it. Default: true |
baseline_days | integer | No | Days of preceding history to use for the rolling baseline (7-90). Default: 28 |
data_source_family | "default" | "all-sources" | "google-wearables" | "google-sources" | No | Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection. Default: "default" |
Parameter schema (JSON)
{
"description": "Parameters for get_overnight_hrv",
"properties": {
"start_date": {
"description": "Inclusive start date (YYYY-MM-DD)",
"title": "Start Date",
"type": "string"
},
"end_date": {
"description": "Inclusive end date (YYYY-MM-DD); range max 30 days",
"title": "End Date",
"type": "string"
},
"with_baseline": {
"default": true,
"description": "If true, fetch a preceding `baseline_days` window and emit per-night delta + Z-score against it.",
"title": "With Baseline",
"type": "boolean"
},
"baseline_days": {
"default": 28,
"description": "Days of preceding history to use for the rolling baseline (7-90).",
"maximum": 90,
"minimum": 7,
"title": "Baseline Days",
"type": "integer"
},
"data_source_family": {
"default": "default",
"description": "Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection.",
"enum": [
"default",
"all-sources",
"google-wearables",
"google-sources"
],
"title": "Data Source Family",
"type": "string"
}
},
"required": [
"start_date",
"end_date"
],
"title": "GetOvernightHrvParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"HrvBaseline": {
"description": "Rolling baseline over the preceding window.",
"properties": {
"mean_daily_rmssd": {
"title": "Mean Daily Rmssd",
"type": "number"
},
"stdev_daily_rmssd": {
"title": "Stdev Daily Rmssd",
"type": "number"
},
"n_nights_in_baseline": {
"title": "N Nights In Baseline",
"type": "integer"
},
"window_days": {
"title": "Window Days",
"type": "integer"
}
},
"required": [
"mean_daily_rmssd",
"stdev_daily_rmssd",
"n_nights_in_baseline",
"window_days"
],
"title": "HrvBaseline",
"type": "object"
},
"HrvNight": {
"description": "One night of HRV data.",
"properties": {
"date": {
"description": "Fitbit's dateTime; the date the measurement ended",
"title": "Date",
"type": "string"
},
"daily_rmssd": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "24-hour RMSSD (ms) — the headline HRV value",
"title": "Daily Rmssd"
},
"deep_rmssd": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Deep-sleep RMSSD (ms) — cleaner signal, less artifact",
"title": "Deep Rmssd"
},
"delta_vs_baseline": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "daily_rmssd minus baseline mean; only present when with_baseline=true and baseline established",
"title": "Delta Vs Baseline"
},
"z_score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "(daily_rmssd - mean) / stdev; only present when with_baseline=true and baseline established",
"title": "Z Score"
}
},
"required": [
"date"
],
"title": "HrvNight",
"type": "object"
}
},
"description": "Result from get_overnight_hrv",
"properties": {
"nights": {
"items": {
"$ref": "#/$defs/HrvNight"
},
"title": "Nights",
"type": "array"
},
"baseline": {
"anyOf": [
{
"$ref": "#/$defs/HrvBaseline"
},
{
"type": "null"
}
],
"default": null,
"description": "Null when with_baseline=false or fewer than 7 baseline nights present"
},
"missing_dates": {
"items": {
"type": "string"
},
"title": "Missing Dates",
"type": "array"
},
"notes": {
"items": {
"type": "string"
},
"title": "Notes",
"type": "array"
}
},
"required": [
"nights",
"missing_dates",
"notes"
],
"title": "GetOvernightHrvResult",
"type": "object"
} # get_skin_temp_variation read
Fetch Fitbit nightly skin-temperature deviation from personal baseline for a date range.
Full description
Per-night skin temperature variation (delta from the user's personal
baseline) for a date range.
The value Fitbit returns is already a relative delta (degrees Celsius
above or below the user's personal baseline, computed server-side from
their first ~30 nights of wear). No additional baseline is layered on top
here — absolute skin temp is meaningless without per-user context, and
the relative delta is the right primitive for illness detection.
Parameters:
start_date (str, required): Inclusive start date (YYYY-MM-DD).
end_date (str, required): Inclusive end date (YYYY-MM-DD). HARD cap at 30 days
(Fitbit's API rejects larger ranges).
data_source_family (str, optional): Google Health source-family selector. Use "google-wearables"
to query tracker/wearable skin-temperature data. This is not exact paired-device selection.
Returns:
GetSkinTempResult with `nights`, `missing_dates`, `notes`.
Notes:
- Requires the `temperature` Fitbit OAuth scope (added 2026-04;
existing users may need to re-authorize).
- `log_type` distinguishes `dedicated_temp_sensor` (Sense, Versa 3+ —
skin contact, more accurate) from `ambient` (noisier, derived from
other sensors).
- First ~3 nights of wear typically return null (Fitbit needs time
to establish the baseline).
- When more than half the requested dates are missing, an explanatory
note is added — the device may not support skin temp at all.
- Tracker-source example:
{"start_date": "2026-06-17", "end_date": "2026-06-17", "data_source_family": "google-wearables"}
Errors:
UNAUTHORIZED: User has not connected Fitbit or token is invalid/expired.
INSUFFICIENT_SCOPE: 'temperature' scope not granted.
VALIDATION_ERROR: Invalid date range (start > end, or > 30 days). | Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Inclusive start date (YYYY-MM-DD) |
end_date | string | Yes | Inclusive end date (YYYY-MM-DD); range max 30 days (Fitbit's hard cap for skin temp) |
data_source_family | "default" | "all-sources" | "google-wearables" | "google-sources" | No | Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection. Default: "default" |
Parameter schema (JSON)
{
"description": "Parameters for get_skin_temp_variation",
"properties": {
"start_date": {
"description": "Inclusive start date (YYYY-MM-DD)",
"title": "Start Date",
"type": "string"
},
"end_date": {
"description": "Inclusive end date (YYYY-MM-DD); range max 30 days (Fitbit's hard cap for skin temp)",
"title": "End Date",
"type": "string"
},
"data_source_family": {
"default": "default",
"description": "Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection.",
"enum": [
"default",
"all-sources",
"google-wearables",
"google-sources"
],
"title": "Data Source Family",
"type": "string"
}
},
"required": [
"start_date",
"end_date"
],
"title": "GetSkinTempParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"SkinTempNight": {
"description": "One night of skin temperature variation. Value is already a delta from the user's\npersonal baseline (Fitbit computes baseline server-side from the first ~30 nights of wear).",
"properties": {
"date": {
"title": "Date",
"type": "string"
},
"nightly_relative_c": {
"description": "Degrees Celsius above (positive) or below the user's personal baseline",
"title": "Nightly Relative C",
"type": "number"
},
"log_type": {
"description": "'dedicated_temp_sensor' (Sense, Versa 3+) or 'ambient' (noisier) or 'unknown'",
"title": "Log Type",
"type": "string"
}
},
"required": [
"date",
"nightly_relative_c",
"log_type"
],
"title": "SkinTempNight",
"type": "object"
}
},
"description": "Result from get_skin_temp_variation",
"properties": {
"nights": {
"items": {
"$ref": "#/$defs/SkinTempNight"
},
"title": "Nights",
"type": "array"
},
"missing_dates": {
"items": {
"type": "string"
},
"title": "Missing Dates",
"type": "array"
},
"notes": {
"items": {
"type": "string"
},
"title": "Notes",
"type": "array"
}
},
"required": [
"nights",
"missing_dates",
"notes"
],
"title": "GetSkinTempResult",
"type": "object"
} # get_sleep_detail read
Fetch Fitbit per-night sleep architecture (stages, onset, WASO, short wakes) for a date range.
Full description
Per-night sleep architecture for a date range.
Returns the data the daily summary doesn't surface: stage breakdown, sleep
onset, time after wakeup, and short-wake events for fragmentation analysis.
Parameters:
start_date (str, required): Inclusive start date (YYYY-MM-DD).
end_date (str, required): Inclusive end date (YYYY-MM-DD). Max 100 days from start.
include_naps (bool, optional): If true, naps populate `naps[]`. Default false.
include_manual (bool, optional): If true, include manually-entered logs.
Default false — manual logs aren't physiologically measured and skew aggregates.
data_source_family (str, optional): Google Health source-family selector. Use "google-wearables"
to query tracker/wearable sleep data. This is not exact paired-device selection.
Returns:
GetSleepDetailResult with `nights`, `naps`, `missing_dates`, `notes`.
Notes:
- `date` is the date the sleep *ended* (Fitbit's dateOfSleep). Late bedtimes
and naps spanning midnight are dated to the next day.
- Stage percentages: deep/light/rem are of minutes_asleep; wake is of time_in_bed.
Matches the convention Oura, Whoop, and clinical research use.
- `data_source` is "classic" when the device or session didn't produce stage data
(older trackers, very short sessions, manual logs); stage fields are null in that case.
- Sleep data may still be processing — Fitbit's meta-pending response is retried
exactly once. If still pending, returns what's available with a note.
- Tracker-source example:
{"start_date": "2026-06-17", "end_date": "2026-06-17", "data_source_family": "google-wearables"}
Errors:
UNAUTHORIZED: User has not connected Fitbit or token is invalid/expired.
INSUFFICIENT_SCOPE: 'sleep' scope not granted.
VALIDATION_ERROR: Invalid date range (start > end, or > 100 days). | Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Inclusive start date (YYYY-MM-DD) |
end_date | string | Yes | Inclusive end date (YYYY-MM-DD); range max 100 days |
include_naps | boolean | No | If true, include nap entries in `naps[]` Default: false |
include_manual | boolean | No | If true, include manually-entered logs (less reliable than auto-detected) Default: false |
data_source_family | "default" | "all-sources" | "google-wearables" | "google-sources" | No | Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection. Default: "default" |
Parameter schema (JSON)
{
"description": "Parameters for get_sleep_detail",
"properties": {
"start_date": {
"description": "Inclusive start date (YYYY-MM-DD)",
"title": "Start Date",
"type": "string"
},
"end_date": {
"description": "Inclusive end date (YYYY-MM-DD); range max 100 days",
"title": "End Date",
"type": "string"
},
"include_naps": {
"default": false,
"description": "If true, include nap entries in `naps[]`",
"title": "Include Naps",
"type": "boolean"
},
"include_manual": {
"default": false,
"description": "If true, include manually-entered logs (less reliable than auto-detected)",
"title": "Include Manual",
"type": "boolean"
},
"data_source_family": {
"default": "default",
"description": "Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection.",
"enum": [
"default",
"all-sources",
"google-wearables",
"google-sources"
],
"title": "Data Source Family",
"type": "string"
}
},
"required": [
"start_date",
"end_date"
],
"title": "GetSleepDetailParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"RecordSource": {
"description": "Best-effort source metadata for a Google Health session record.",
"properties": {
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Google Health dataSource.type, e.g. DEVICE or USER_INPUT",
"title": "Type"
},
"application_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source application name when reported",
"title": "Application Name"
},
"application_package_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source application package when reported",
"title": "Application Package Name"
},
"device_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device model when reported",
"title": "Device Model"
},
"device_manufacturer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device manufacturer when reported",
"title": "Device Manufacturer"
},
"device_uid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable device identifier when reported",
"title": "Device Uid"
},
"device_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device type/category when reported",
"title": "Device Type"
}
},
"title": "RecordSource",
"type": "object"
},
"ShortWakes": {
"description": "Aggregated short-wake events (<3min). For most uses count + total minutes is enough.",
"properties": {
"count": {
"title": "Count",
"type": "integer"
},
"total_min": {
"title": "Total Min",
"type": "number"
}
},
"required": [
"count",
"total_min"
],
"title": "ShortWakes",
"type": "object"
},
"SleepNight": {
"description": "One sleep log (main sleep or nap).",
"properties": {
"date": {
"description": "Date the sleep ended (Fitbit's dateOfSleep)",
"title": "Date",
"type": "string"
},
"main_sleep": {
"description": "True for primary nightly sleep; False for naps",
"title": "Main Sleep",
"type": "boolean"
},
"log_type": {
"description": "'auto_detected' or 'manual'",
"title": "Log Type",
"type": "string"
},
"start_time": {
"title": "Start Time",
"type": "string"
},
"end_time": {
"title": "End Time",
"type": "string"
},
"time_in_bed_min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Time In Bed Min"
},
"minutes_asleep": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Minutes Asleep"
},
"efficiency": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Asleep / time_in_bed, 0-1",
"title": "Efficiency"
},
"minutes_to_fall_asleep": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Minutes To Fall Asleep"
},
"minutes_after_wakeup": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Minutes After Wakeup"
},
"stages": {
"anyOf": [
{
"$ref": "#/$defs/SleepStages"
},
{
"type": "null"
}
],
"default": null,
"description": "Null when data_source='classic'"
},
"stage_counts": {
"anyOf": [
{
"$ref": "#/$defs/SleepStageCounts"
},
{
"type": "null"
}
],
"default": null,
"description": "Null when data_source='classic'"
},
"short_wakes": {
"$ref": "#/$defs/ShortWakes"
},
"data_source": {
"description": "'stages' if device produced staged data, 'classic' for older trackers / manual logs",
"enum": [
"stages",
"classic"
],
"title": "Data Source",
"type": "string"
},
"source": {
"anyOf": [
{
"$ref": "#/$defs/RecordSource"
},
{
"type": "null"
}
],
"default": null,
"description": "Best-effort Google Health source metadata"
}
},
"required": [
"date",
"main_sleep",
"log_type",
"start_time",
"end_time",
"short_wakes",
"data_source"
],
"title": "SleepNight",
"type": "object"
},
"SleepStageCounts": {
"description": "Number of discrete bouts per stage (for fragmentation analysis).",
"properties": {
"deep": {
"title": "Deep",
"type": "integer"
},
"light": {
"title": "Light",
"type": "integer"
},
"rem": {
"title": "Rem",
"type": "integer"
},
"wake": {
"title": "Wake",
"type": "integer"
}
},
"required": [
"deep",
"light",
"rem",
"wake"
],
"title": "SleepStageCounts",
"type": "object"
},
"SleepStages": {
"description": "Per-stage minutes and percentages. deep/light/rem percentages are of minutes_asleep; wake_pct is of time_in_bed.",
"properties": {
"deep_min": {
"title": "Deep Min",
"type": "integer"
},
"light_min": {
"title": "Light Min",
"type": "integer"
},
"rem_min": {
"title": "Rem Min",
"type": "integer"
},
"wake_min": {
"title": "Wake Min",
"type": "integer"
},
"deep_pct": {
"title": "Deep Pct",
"type": "number"
},
"light_pct": {
"title": "Light Pct",
"type": "number"
},
"rem_pct": {
"title": "Rem Pct",
"type": "number"
},
"wake_pct": {
"title": "Wake Pct",
"type": "number"
}
},
"required": [
"deep_min",
"light_min",
"rem_min",
"wake_min",
"deep_pct",
"light_pct",
"rem_pct",
"wake_pct"
],
"title": "SleepStages",
"type": "object"
}
},
"description": "Result from get_sleep_detail",
"properties": {
"nights": {
"description": "Main-sleep logs in the requested range",
"items": {
"$ref": "#/$defs/SleepNight"
},
"title": "Nights",
"type": "array"
},
"naps": {
"description": "Nap logs (populated only when include_naps=true)",
"items": {
"$ref": "#/$defs/SleepNight"
},
"title": "Naps",
"type": "array"
},
"missing_dates": {
"description": "Dates in range with no sleep log present",
"items": {
"type": "string"
},
"title": "Missing Dates",
"type": "array"
},
"notes": {
"description": "Per-night caveats (e.g. classic-only logs, meta-pending fallback)",
"items": {
"type": "string"
},
"title": "Notes",
"type": "array"
}
},
"required": [
"nights",
"naps",
"missing_dates",
"notes"
],
"title": "GetSleepDetailResult",
"type": "object"
} # get_sleep_health_panel read
Fuse Fitbit sleep architecture, HRV, breathing rate, skin temperature, and resting HR into a per-night panel with computed flags and a 0-100 recovery score.
Full description
Multi-signal sleep+recovery panel for a date range.
Composes the four sleep-and-recovery primitives (`get_sleep_detail`,
`get_overnight_hrv`, `get_breathing_rate`, `get_skin_temp_variation`)
plus resting HR from `get_daily_summary`, joins by date, and emits
per-night flags (low_hrv, high_rhr, cardiovascular_strain,
elevated_temp_and_breathing, fragmented_sleep, low_deep_sleep,
low_rem) plus a 0-100 composite recovery score.
Parameters:
start_date (str, required): Inclusive start date (YYYY-MM-DD).
end_date (str, required): Inclusive end date (YYYY-MM-DD).
Max 30 days — skin temp's hard cap is the binding constraint.
baseline_days (int, optional): Window for HRV/breathing/RHR
baselines. Default 28.
include_classic (bool, optional): Include nights where sleep_detail's
data_source='classic' (no stage breakdown). Default false.
data_source_family (str, optional): Google Health source-family selector. Use "google-wearables"
to build the panel from tracker/wearable data. This is not exact paired-device selection.
Returns:
GetSleepHealthPanelResult with `nights`, `summary`, `missing_dates`, `notes`.
Notes:
- Recovery score is a HEURISTIC, not a clinical metric.
Missing signals contribute zero penalty (correct: missing data
shouldn't artificially worsen the score).
- Trend signals only emit when ≥14 nights of recent data are present
and delta exceeds a noise threshold.
- Scope handling: `sleep` is required (hard fail without it). Other
missing scopes degrade the panel gracefully — the relevant fields
come back null, and dependent flags are suppressed automatically
since their inputs are None.
- Tracker-source example:
{"start_date": "2026-06-01", "end_date": "2026-06-17", "data_source_family": "google-wearables"}
Errors:
UNAUTHORIZED: User has not connected Fitbit or token is invalid/expired.
INSUFFICIENT_SCOPE: 'sleep' scope not granted (hard fail).
VALIDATION_ERROR: Invalid date range. | Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Inclusive start date (YYYY-MM-DD) |
end_date | string | Yes | Inclusive end date (YYYY-MM-DD); range max 30 days (skin temp's binding constraint) |
baseline_days | integer | No | Window size for HRV/breathing/RHR baselines Default: 28 |
include_classic | boolean | No | If true, include nights where sleep_detail's data_source='classic' (no stage breakdown) Default: false |
data_source_family | "default" | "all-sources" | "google-wearables" | "google-sources" | No | Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection. Default: "default" |
Parameter schema (JSON)
{
"description": "Parameters for get_sleep_health_panel",
"properties": {
"start_date": {
"description": "Inclusive start date (YYYY-MM-DD)",
"title": "Start Date",
"type": "string"
},
"end_date": {
"description": "Inclusive end date (YYYY-MM-DD); range max 30 days (skin temp's binding constraint)",
"title": "End Date",
"type": "string"
},
"baseline_days": {
"default": 28,
"description": "Window size for HRV/breathing/RHR baselines",
"maximum": 90,
"minimum": 7,
"title": "Baseline Days",
"type": "integer"
},
"include_classic": {
"default": false,
"description": "If true, include nights where sleep_detail's data_source='classic' (no stage breakdown)",
"title": "Include Classic",
"type": "boolean"
},
"data_source_family": {
"default": "default",
"description": "Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection.",
"enum": [
"default",
"all-sources",
"google-wearables",
"google-sources"
],
"title": "Data Source Family",
"type": "string"
}
},
"required": [
"start_date",
"end_date"
],
"title": "GetSleepHealthPanelParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"RecordSource": {
"description": "Best-effort source metadata for a Google Health session record.",
"properties": {
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Google Health dataSource.type, e.g. DEVICE or USER_INPUT",
"title": "Type"
},
"application_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source application name when reported",
"title": "Application Name"
},
"application_package_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source application package when reported",
"title": "Application Package Name"
},
"device_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device model when reported",
"title": "Device Model"
},
"device_manufacturer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device manufacturer when reported",
"title": "Device Manufacturer"
},
"device_uid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable device identifier when reported",
"title": "Device Uid"
},
"device_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device type/category when reported",
"title": "Device Type"
}
},
"title": "RecordSource",
"type": "object"
},
"SleepHealthFlag": {
"description": "A computed health signal flag for one night.",
"properties": {
"type": {
"enum": [
"low_hrv",
"high_rhr",
"cardiovascular_strain",
"elevated_temp_and_breathing",
"fragmented_sleep",
"low_deep_sleep",
"low_rem"
],
"title": "Type",
"type": "string"
},
"severity": {
"enum": [
"watch",
"warn",
"alert"
],
"title": "Severity",
"type": "string"
},
"rationale": {
"description": "Human-readable explanation of why this flag fired",
"title": "Rationale",
"type": "string"
}
},
"required": [
"type",
"severity",
"rationale"
],
"title": "SleepHealthFlag",
"type": "object"
},
"SleepHealthPanelNight": {
"description": "One night's worth of fused signals + computed flags + recovery score.",
"properties": {
"date": {
"title": "Date",
"type": "string"
},
"minutes_asleep": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Minutes Asleep"
},
"efficiency": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Efficiency"
},
"minutes_to_fall_asleep": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Minutes To Fall Asleep"
},
"deep_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Deep Pct"
},
"rem_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Rem Pct"
},
"wake_min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Wake Min"
},
"short_wake_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Short Wake Count"
},
"daily_rmssd": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Daily Rmssd"
},
"deep_rmssd": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Deep Rmssd"
},
"hrv_z": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Hrv Z"
},
"breathing_rate": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Breathing Rate"
},
"breathing_z": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Breathing Z"
},
"breathing_rate_source": {
"anyOf": [
{
"$ref": "#/$defs/RecordSource"
},
{
"type": "null"
}
],
"default": null
},
"skin_temp_delta_c": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Skin Temp Delta C"
},
"resting_hr": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Resting Hr"
},
"rhr_z": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Rhr Z"
},
"flags": {
"items": {
"$ref": "#/$defs/SleepHealthFlag"
},
"title": "Flags",
"type": "array"
},
"composite_recovery_score": {
"description": "0-100 heuristic; not a clinical metric. Higher is better recovery.",
"title": "Composite Recovery Score",
"type": "integer"
}
},
"required": [
"date",
"flags",
"composite_recovery_score"
],
"title": "SleepHealthPanelNight",
"type": "object"
},
"SleepHealthRangeSummary": {
"description": "Range-level aggregates plus 14-day-vs-prior-14-day trend signals (when range allows).",
"properties": {
"n_nights": {
"title": "N Nights",
"type": "integer"
},
"avg_minutes_asleep": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Avg Minutes Asleep"
},
"avg_efficiency": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Avg Efficiency"
},
"avg_deep_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Avg Deep Pct"
},
"avg_rem_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Avg Rem Pct"
},
"avg_daily_rmssd": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Avg Daily Rmssd"
},
"avg_breathing_rate": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Avg Breathing Rate"
},
"n_flagged_nights": {
"title": "N Flagged Nights",
"type": "integer"
},
"trend_signals": {
"description": "Human-readable trend movements vs prior 14 days; only emitted when delta exceeds a noise threshold",
"items": {
"type": "string"
},
"title": "Trend Signals",
"type": "array"
}
},
"required": [
"n_nights",
"n_flagged_nights",
"trend_signals"
],
"title": "SleepHealthRangeSummary",
"type": "object"
}
},
"description": "Result from get_sleep_health_panel",
"properties": {
"nights": {
"items": {
"$ref": "#/$defs/SleepHealthPanelNight"
},
"title": "Nights",
"type": "array"
},
"summary": {
"$ref": "#/$defs/SleepHealthRangeSummary"
},
"missing_dates": {
"items": {
"type": "string"
},
"title": "Missing Dates",
"type": "array"
},
"notes": {
"description": "Caveats including missing scopes (degraded panel) and data quality concerns",
"items": {
"type": "string"
},
"title": "Notes",
"type": "array"
}
},
"required": [
"nights",
"summary",
"missing_dates",
"notes"
],
"title": "GetSleepHealthPanelResult",
"type": "object"
} # get_trends read
Compute rolling statistics and percent change for one Fitbit metric and return trend summaries over time.
Full description
Compute rolling window statistics and percent change for one metric.
Parameters:
metric (str, required): Metric to analyze. Valid values: "steps", "resting_hr", "hrv", "sleep_duration", "calories"
window_days (int, required): Number of days in the rolling window (e.g., 7 for week, 28 for month)
end_date (str, required): End date of window in format YYYY-MM-DD (e.g., "2025-11-10")
compare_to (str, optional): Comparison period. Valid values:
- "prior_window": Compare to previous window of same length
- "prior_week": Compare to same weekdays in prior week
- "baseline": Compare to longer-term baseline
Default: "prior_window"
data_source_family (str, optional): Google Health source-family selector. Use "google-wearables"
to compute the trend from tracker/wearable data. This is not exact paired-device selection.
Returns:
GetTrendsResult with:
- window_days: Echo of window size
- end_date: Echo of end date
- mean: Average value for the metric in the window
- std_dev: Standard deviation (variability)
- change_pct: Percent change vs comparison period (null if no comparison)
Example:
Get 7-day trend for steps ending today, compared to previous 7 days:
{"metric": "steps", "window_days": 7, "end_date": "2025-11-10", "compare_to": "prior_window"}
Get the same trend from tracker/wearable sources:
{"metric": "steps", "window_days": 7, "end_date": "2026-06-17", "data_source_family": "google-wearables"}
Errors:
UNAUTHORIZED: Could not authenticate
VALIDATION_ERROR: Invalid metric name or invalid compare_to value
DATA_GAP: Insufficient data for requested window | Parameter | Type | Required | Description |
|---|---|---|---|
metric | "steps" | "activity_minutes" | "active_zone_minutes" | "resting_hr" | "hrv" | "sleep_efficiency" | "sleep_duration" | "spo2" | "vo2_max" | Yes | Metric to analyze |
window_days | integer | No | Window size in days Default: 28 |
end_date | string | Yes | End date (YYYY-MM-DD) |
compare_to | "prior_window" | "prior_week" | "prior_month" | No | Comparison period Default: "prior_window" |
data_source_family | "default" | "all-sources" | "google-wearables" | "google-sources" | No | Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection. Default: "default" |
Parameter schema (JSON)
{
"description": "Parameters for get_trends",
"properties": {
"metric": {
"description": "Metric to analyze",
"enum": [
"steps",
"activity_minutes",
"active_zone_minutes",
"resting_hr",
"hrv",
"sleep_efficiency",
"sleep_duration",
"spo2",
"vo2_max"
],
"title": "Metric",
"type": "string"
},
"window_days": {
"default": 28,
"description": "Window size in days",
"minimum": 7,
"title": "Window Days",
"type": "integer"
},
"end_date": {
"description": "End date (YYYY-MM-DD)",
"title": "End Date",
"type": "string"
},
"compare_to": {
"default": "prior_window",
"description": "Comparison period",
"enum": [
"prior_window",
"prior_week",
"prior_month"
],
"title": "Compare To",
"type": "string"
},
"data_source_family": {
"default": "default",
"description": "Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection.",
"enum": [
"default",
"all-sources",
"google-wearables",
"google-sources"
],
"title": "Data Source Family",
"type": "string"
}
},
"required": [
"metric",
"end_date"
],
"title": "GetTrendsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"description": "Result from get_trends",
"properties": {
"metric": {
"title": "Metric",
"type": "string"
},
"window_days": {
"title": "Window Days",
"type": "integer"
},
"end_date": {
"title": "End Date",
"type": "string"
},
"mean": {
"title": "Mean",
"type": "number"
},
"std_dev": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Std Dev"
},
"min_value": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Min Value"
},
"max_value": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Value"
},
"change_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Change Pct"
},
"comparison_mean": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Comparison Mean"
}
},
"required": [
"metric",
"window_days",
"end_date",
"mean"
],
"title": "GetTrendsResult",
"type": "object"
} # get_user_permissions read
Read granted Fitbit/Google Health OAuth scopes and return which data types and access levels are available for the account.
Full description
Return the Fitbit or Google Health OAuth scopes currently granted for the user/account.
This helps understand which data are available and set expectations
(e.g., intraday HR requires specific permissions).
Parameters:
None - This tool takes no parameters.
Returns:
GetUserPermissionsResult with:
- scopes: Array of permission names (e.g., ["Activity", "Heart Rate", "Sleep", "Settings"])
Common permissions:
- Activity: Step counts, calories, active minutes
- Heart Rate: Resting HR, intraday HR, HRV
- Sleep: Sleep duration, efficiency, stages
- Settings: Paired tracker/smartwatch listing
- Nutrition: Food logging
- Weight: Weight and body composition
Errors:
UNAUTHORIZED: User has not connected Fitbit/Google Health or token is invalid/expired No parameters.
Parameter schema (JSON)
{
"description": "Parameters for get_user_permissions (none required)",
"properties": {},
"title": "GetUserPermissionsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"description": "Result from get_user_permissions",
"properties": {
"scopes": {
"description": "List of granted permission names (e.g., 'Activity', 'Heart Rate', 'Settings')",
"items": {
"type": "string"
},
"title": "Scopes",
"type": "array"
}
},
"required": [
"scopes"
],
"title": "GetUserPermissionsResult",
"type": "object"
} # get_workout_sessions read
Fetch Fitbit workout sessions for a date range and return session-level exercise details like type, duration, zones, and calories.
Full description
Fetch exercise sessions (workout logs) for a date range.
Returns session-level data for each logged or auto-detected workout,
including activity type, duration, heart rate zones, calories, and distance.
Useful for reviewing training history and analyzing exercise patterns.
Parameters:
start_date (str, required): Start date in YYYY-MM-DD format. Must be <= end_date.
end_date (str, required): End date in YYYY-MM-DD format. Must be >= start_date.
activity_type (str, optional): Filter by human-readable activity name.
Case-insensitive. Common values: "Walk", "Run", "Outdoor Bike", "Swim",
"Yoga", "Weights", "Treadmill", "HIIT". Partial matches not supported --
use exact name as returned by Fitbit (visible in activity_name field of results).
activity_type_id (int, optional): Filter by Fitbit activity type ID (e.g. 90013 = Walk,
1071 = Outdoor Bike, 90024 = Swim). Ignored if activity_type is also provided.
min_duration_minutes (int, optional): Exclude sessions shorter than this many minutes.
Useful for filtering out incidental movement (e.g. min_duration_minutes=20
to focus on intentional workouts).
max_duration_minutes (int, optional): Exclude sessions longer than this many minutes.
sort (str, optional): Sort order: "asc" or "desc" by start time. Default: "desc"
limit (int, optional): Max sessions to return (1-1000). Default: 20
offset (int, optional): Pagination offset. Default: 0
data_source_family (str, optional): Google Health source-family selector. Use "google-wearables"
to query tracker/wearable workout sessions. This is not exact paired-device selection.
Returns:
GetWorkoutSessionsResult with:
- sessions: Array of workout session objects
- total: Number of sessions returned (after filtering)
- has_more: Whether more sessions are available via pagination
- distance_unit: 'km' or 'mi' based on user's Fitbit profile setting
- timezone: User's Fitbit-configured timezone (e.g. "America/New_York")
Notes:
- Duration filtering is applied within the Lambda (not on Fitbit's servers)
before pagination -- limit/offset reflect the filtered result set.
- Multiple Fitbit API calls are made when fetching >100 sessions or when
duration filters are active (up to 10 pages of 100).
- log_type is either "auto_detected" or "manual"
- heart_rate_zones is only populated if the user has HR data for the session
- distance will be null for activities where distance is not tracked
- Requires the Activity OAuth scope
- Tracker-source example:
{"start_date": "2026-06-01", "end_date": "2026-06-17", "data_source_family": "google-wearables"}
Errors:
UNAUTHORIZED: Could not authenticate
INSUFFICIENT_SCOPE: Missing required Activity scope
VALIDATION_ERROR: Invalid date range or unrecognized activity_type string | Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Start date (YYYY-MM-DD). Must be <= end_date |
end_date | string | Yes | End date (YYYY-MM-DD). Must be >= start_date |
activity_type | string | null | No | Filter by human-readable activity name (case-insensitive). Common values: "Walk", "Run", "Outdoor Bike", "Swim", "Yoga", "Weights", "Treadmill", "HIIT". Takes precedence over activity_type_id if both are provided. |
activity_type_id | integer | null | No | Filter by Fitbit activity type ID (e.g. 90013 = Walk, 1071 = Outdoor Bike, 90024 = Swim). Ignored if activity_type is also provided. |
min_duration_minutes | integer | null | No | Exclude sessions shorter than this many minutes. Useful for filtering out incidental movement (e.g. min_duration_minutes=20 to focus on intentional workouts). |
max_duration_minutes | integer | null | No | Exclude sessions longer than this many minutes. |
sort | "asc" | "desc" | No | Sort order: 'asc' or 'desc' Default: "desc" |
limit | integer | No | Max sessions to return (1-1000) Default: 20 |
offset | integer | No | Pagination offset Default: 0 |
data_source_family | "default" | "all-sources" | "google-wearables" | "google-sources" | No | Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection. Default: "default" |
Parameter schema (JSON)
{
"description": "Parameters for get_workout_sessions",
"properties": {
"start_date": {
"description": "Start date (YYYY-MM-DD). Must be <= end_date",
"title": "Start Date",
"type": "string"
},
"end_date": {
"description": "End date (YYYY-MM-DD). Must be >= start_date",
"title": "End Date",
"type": "string"
},
"activity_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Filter by human-readable activity name (case-insensitive). Common values: \"Walk\", \"Run\", \"Outdoor Bike\", \"Swim\", \"Yoga\", \"Weights\", \"Treadmill\", \"HIIT\". Takes precedence over activity_type_id if both are provided.",
"title": "Activity Type"
},
"activity_type_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Filter by Fitbit activity type ID (e.g. 90013 = Walk, 1071 = Outdoor Bike, 90024 = Swim). Ignored if activity_type is also provided.",
"title": "Activity Type Id"
},
"min_duration_minutes": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Exclude sessions shorter than this many minutes. Useful for filtering out incidental movement (e.g. min_duration_minutes=20 to focus on intentional workouts).",
"title": "Min Duration Minutes"
},
"max_duration_minutes": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Exclude sessions longer than this many minutes.",
"title": "Max Duration Minutes"
},
"sort": {
"default": "desc",
"description": "Sort order: 'asc' or 'desc'",
"enum": [
"asc",
"desc"
],
"title": "Sort",
"type": "string"
},
"limit": {
"default": 20,
"description": "Max sessions to return (1-1000)",
"maximum": 1000,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"offset": {
"default": 0,
"description": "Pagination offset",
"minimum": 0,
"title": "Offset",
"type": "integer"
},
"data_source_family": {
"default": "default",
"description": "Google Health source-family selector. Use 'default' to preserve current canonical behavior. Use 'google-wearables' when the user asks for tracker/wearable data such as data from a Fitbit tracker. 'all-sources' explicitly asks Google Health for all sources, and 'google-sources' asks for Google first-party sources. This is a source-family filter, not exact paired-device selection.",
"enum": [
"default",
"all-sources",
"google-wearables",
"google-sources"
],
"title": "Data Source Family",
"type": "string"
}
},
"required": [
"start_date",
"end_date"
],
"title": "GetWorkoutSessionsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"HeartRateZones": {
"description": "Heart rate zone breakdown for a workout session",
"properties": {
"out_of_range_minutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Minutes in Out of Range zone",
"title": "Out Of Range Minutes"
},
"fat_burn_minutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Minutes in Fat Burn zone",
"title": "Fat Burn Minutes"
},
"cardio_minutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Minutes in Cardio zone",
"title": "Cardio Minutes"
},
"peak_minutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Minutes in Peak zone",
"title": "Peak Minutes"
}
},
"title": "HeartRateZones",
"type": "object"
},
"RecordSource": {
"description": "Best-effort source metadata for a Google Health session record.",
"properties": {
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Google Health dataSource.type, e.g. DEVICE or USER_INPUT",
"title": "Type"
},
"application_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source application name when reported",
"title": "Application Name"
},
"application_package_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source application package when reported",
"title": "Application Package Name"
},
"device_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device model when reported",
"title": "Device Model"
},
"device_manufacturer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device manufacturer when reported",
"title": "Device Manufacturer"
},
"device_uid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable device identifier when reported",
"title": "Device Uid"
},
"device_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source device type/category when reported",
"title": "Device Type"
}
},
"title": "RecordSource",
"type": "object"
},
"WorkoutSession": {
"description": "A single workout/exercise session",
"properties": {
"log_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Unique log ID for this session (null in Google Health mode; sessions are identified by start_time)",
"title": "Log Id"
},
"activity_name": {
"description": "Name of the activity (e.g. 'Run', 'Walk')",
"title": "Activity Name",
"type": "string"
},
"activity_type_id": {
"description": "Fitbit activity type ID",
"title": "Activity Type Id",
"type": "integer"
},
"start_time": {
"description": "Session start time (ISO format)",
"title": "Start Time",
"type": "string"
},
"duration_ms": {
"description": "Total duration in milliseconds",
"title": "Duration Ms",
"type": "integer"
},
"duration_minutes": {
"description": "Total duration in minutes",
"title": "Duration Minutes",
"type": "integer"
},
"calories": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Calories burned",
"title": "Calories"
},
"distance": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Distance covered (null for non-distance activities). Unit is specified in distance_unit on the result.",
"title": "Distance"
},
"steps": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Step count during session",
"title": "Steps"
},
"log_type": {
"description": "'auto_detected' or 'manual'",
"title": "Log Type",
"type": "string"
},
"heart_rate_zones": {
"anyOf": [
{
"$ref": "#/$defs/HeartRateZones"
},
{
"type": "null"
}
],
"default": null,
"description": "Heart rate zone breakdown (requires HR scope)"
},
"average_heart_rate": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Average heart rate during session",
"title": "Average Heart Rate"
},
"active_duration_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Active duration in milliseconds",
"title": "Active Duration Ms"
},
"source": {
"anyOf": [
{
"$ref": "#/$defs/RecordSource"
},
{
"type": "null"
}
],
"default": null,
"description": "Best-effort Google Health source metadata"
}
},
"required": [
"activity_name",
"activity_type_id",
"start_time",
"duration_ms",
"duration_minutes",
"log_type"
],
"title": "WorkoutSession",
"type": "object"
}
},
"description": "Result from get_workout_sessions",
"properties": {
"sessions": {
"items": {
"$ref": "#/$defs/WorkoutSession"
},
"title": "Sessions",
"type": "array"
},
"total": {
"description": "Number of sessions returned",
"title": "Total",
"type": "integer"
},
"has_more": {
"description": "Whether more sessions are available via pagination",
"title": "Has More",
"type": "boolean"
},
"distance_unit": {
"description": "Unit for distance values: 'km' or 'mi' (based on user's Fitbit profile setting)",
"title": "Distance Unit",
"type": "string"
},
"timezone": {
"description": "User's Fitbit-configured timezone (e.g. 'America/New_York'). All start_time values are in this timezone.",
"title": "Timezone",
"type": "string"
},
"notes": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Caveats (e.g. log_id is not available in Google Health mode)",
"title": "Notes"
}
},
"required": [
"sessions",
"total",
"has_more",
"distance_unit",
"timezone"
],
"title": "GetWorkoutSessionsResult",
"type": "object"
} # list_connected_devices read
List Google Health paired devices visible to the connected account.
Full description
List paired devices reported by Google Health for the connected account.
Parameters:
page_size (int, optional): Maximum paired devices to request per provider page. Default 100.
Returns:
ListConnectedDevicesResult with normalized best-effort device metadata.
Notes:
- Requires the Google Health Settings permission
(https://www.googleapis.com/auth/googlehealth.settings.readonly).
- To query metric data from tracker/wearable sources, use
data_source_family="google-wearables" on the metric tools.
- data_source_family is a Google Health source-family filter, not exact
paired-device selection.
- Google Health may return only a paired-device resource name and type
(for example TRACKER); battery, device version, model, manufacturer,
platform, and last-seen fields are best-effort and may be null.
Errors:
UNAUTHORIZED: User has not connected Google Health or token is invalid/expired.
INSUFFICIENT_SCOPE: Missing Google Health Settings permission.
NOT_SUPPORTED: The current connection is a legacy Fitbit token. | Parameter | Type | Required | Description |
|---|---|---|---|
page_size | integer | No | Maximum paired devices to request per provider page Default: 100 |
Parameter schema (JSON)
{
"description": "Parameters for list_connected_devices",
"properties": {
"page_size": {
"default": 100,
"description": "Maximum paired devices to request per provider page",
"maximum": 100,
"minimum": 1,
"title": "Page Size",
"type": "integer"
}
},
"title": "ListConnectedDevicesParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"ConnectedDevice": {
"description": "A Google Health paired device, normalized best-effort from the provider payload.",
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Provider device resource name or identifier",
"title": "Name"
},
"battery": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Battery state when reported, such as High, Medium, Low, or Empty",
"title": "Battery"
},
"battery_level": {
"anyOf": [
{
"maximum": 100,
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Battery percentage when reported; Google Health may omit this field",
"title": "Battery Level"
},
"device_version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Fitbit-style product/device version when reported; Google Health may omit this field",
"title": "Device Version"
},
"display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Provider display name when reported; falls back to the resource name if no human-readable name is available",
"title": "Display Name"
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Device model when reported; Google Health may omit this field",
"title": "Model"
},
"manufacturer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Device manufacturer when reported; Google Health may omit this field",
"title": "Manufacturer"
},
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Device type/category when reported, such as TRACKER or SCALE",
"title": "Type"
},
"platform": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Device platform when reported; Google Health may omit this field",
"title": "Platform"
},
"last_seen_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Last seen timestamp when reported; Google Health may omit this field",
"title": "Last Seen Time"
}
},
"title": "ConnectedDevice",
"type": "object"
}
},
"description": "Result from list_connected_devices",
"properties": {
"devices": {
"items": {
"$ref": "#/$defs/ConnectedDevice"
},
"title": "Devices",
"type": "array"
},
"total": {
"description": "Number of devices returned",
"title": "Total",
"type": "integer"
},
"notes": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Caveats about provider payload coverage",
"title": "Notes"
}
},
"required": [
"devices",
"total"
],
"title": "ListConnectedDevicesResult",
"type": "object"
}