Ōura Ring — Tool Reference
Access sleep, readiness, activity, and other health data from your Ōura Ring
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 deviations vs a rolling baseline for selected Oura metrics and return Z-score anomaly insights for coaching/wellness use.
Full description
Detect deviations vs a rolling baseline for selected metrics.
Uses Z-score analysis to identify values outside normal range.
This is for coaching/wellness insights only, NOT medical diagnosis.
Parameters:
metrics (array, required): Metrics to analyze:
- "resting_hr": Resting heart rate
- "hrv": Heart rate variability balance
- "sleep_efficiency": Sleep efficiency percentage
- "sleep_duration": Total sleep hours
- "spo2": Blood oxygen saturation
- "readiness_score": Daily readiness score
- "activity_score": Daily activity score
- "temperature_deviation": Body temperature deviation
window_days (int, optional): Baseline window in days (min 7). Default: 14
end_date (str, required): End date in YYYY-MM-DD format
sensitivity (str, optional): Detection sensitivity:
- "low": >3 std deviations (extreme outliers)
- "medium": >2 std deviations (significant)
- "high": >1.5 std deviations (any unusual)
Default: "medium"
min_confirmed_days (int, optional): Minimum consecutive days. Default: 2
Returns:
DetectAnomaliesResult with:
- anomalies: Array of detected anomalies with metric, dates, z_score, direction, rationale
Errors:
UNAUTHORIZED: Could not authenticate
VALIDATION_ERROR: Invalid metric
DATA_GAP: Insufficient data for detection | Parameter | Type | Required | Description |
|---|---|---|---|
metrics | array<"resting_hr" | "hrv" | "sleep_efficiency" | "sleep_duration" | "spo2" | "readiness_score" | "activity_score" | "temperature_deviation"> | Yes | Metrics to check for anomalies |
window_days | integer | No | Baseline window in days 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 for confirmed anomaly Default: 2 |
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",
"readiness_score",
"activity_score",
"temperature_deviation"
],
"type": "string"
},
"title": "Metrics",
"type": "array"
},
"window_days": {
"default": 14,
"description": "Baseline window in days",
"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 for confirmed anomaly",
"minimum": 1,
"title": "Min Confirmed Days",
"type": "integer"
}
},
"required": [
"metrics",
"end_date"
],
"title": "DetectAnomaliesParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"Anomaly": {
"description": "Detected anomaly",
"properties": {
"metric": {
"description": "Metric that showed anomaly",
"title": "Metric",
"type": "string"
},
"start_date": {
"description": "Start date of anomaly",
"title": "Start Date",
"type": "string"
},
"end_date": {
"description": "End date of anomaly",
"title": "End Date",
"type": "string"
},
"z_score": {
"description": "Z-score (standard deviations from mean)",
"title": "Z Score",
"type": "number"
},
"direction": {
"description": "Direction of anomaly",
"enum": [
"up",
"down"
],
"title": "Direction",
"type": "string"
},
"rationale": {
"description": "Human-readable explanation",
"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": {
"description": "List of detected anomalies",
"items": {
"$ref": "#/$defs/Anomaly"
},
"title": "Anomalies",
"type": "array"
}
},
"required": [
"anomalies"
],
"title": "DetectAnomaliesResult",
"type": "object"
} # get_breathing_rate read
Fetch Oura nightly average breathing rate (breaths/min) for a date range; per-stage breakdown not available — Fitbit's tool has it, Oura's API does not.
Full description
Per-night average breathing rate for a date range.
Reads `average_breath` (breaths/min) from the primary `long_sleep` session
per day. 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`.
Note: Oura's API exposes only the nightly average — there is no per-stage
(REM/light/deep) breakdown. Fitbit's equivalent tool offers per-stage
rates; Oura's equivalent must not promise that.
Parameters:
start_date (str, required): Inclusive start date (YYYY-MM-DD).
end_date (str, required): Inclusive end date (YYYY-MM-DD).
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.
Returns:
GetBreathingRateResult with `nights`, `baseline`, `missing_dates`, `notes`.
Errors:
UNAUTHORIZED: Could not authenticate.
VALIDATION_ERROR: Invalid date format or start_date > end_date. | Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Inclusive start date (YYYY-MM-DD) |
end_date | string | Yes | Inclusive end date (YYYY-MM-DD) |
with_baseline | boolean | No | If true, fetch a preceding baseline_days window and emit per-night delta + Z-score. Default: true |
baseline_days | integer | No | Days of preceding history to use for the rolling baseline (7-90). Default: 28 |
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)",
"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.",
"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"
}
},
"required": [
"start_date",
"end_date"
],
"title": "GetBreathingRateParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"OuraBreathingRateBaseline": {
"description": "Rolling baseline of nightly breathing rate (breaths/min).",
"properties": {
"mean_average_breath_per_min": {
"title": "Mean Average Breath Per Min",
"type": "number"
},
"stdev_average_breath_per_min": {
"title": "Stdev Average Breath Per Min",
"type": "number"
},
"n_nights_in_baseline": {
"title": "N Nights In Baseline",
"type": "integer"
},
"window_days": {
"title": "Window Days",
"type": "integer"
}
},
"required": [
"mean_average_breath_per_min",
"stdev_average_breath_per_min",
"n_nights_in_baseline",
"window_days"
],
"title": "OuraBreathingRateBaseline",
"type": "object"
},
"OuraBreathingRateNight": {
"description": "One night of breathing rate data. Oura's API only exposes nightly average — there is NO\nper-stage breakdown (Fitbit's tool has REM/light/deep splits; Oura's API does not).",
"properties": {
"date": {
"description": "Day-of-night (YYYY-MM-DD)",
"title": "Date",
"type": "string"
},
"average_breath_per_min": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Nightly average breathing rate in breaths/min (Oura's /sleep endpoint returns this directly in breaths/min)",
"title": "Average Breath Per Min"
},
"delta_vs_baseline": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "average_breath_per_min minus baseline mean; only with baseline established",
"title": "Delta Vs Baseline"
},
"z_score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "(average_breath_per_min - mean) / stdev; only with baseline established",
"title": "Z Score"
}
},
"required": [
"date"
],
"title": "OuraBreathingRateNight",
"type": "object"
}
},
"description": "Result from get_breathing_rate",
"properties": {
"nights": {
"items": {
"$ref": "#/$defs/OuraBreathingRateNight"
},
"title": "Nights",
"type": "array"
},
"baseline": {
"anyOf": [
{
"$ref": "#/$defs/OuraBreathingRateBaseline"
},
{
"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_cardiovascular_age read
Fetch Oura daily cardiovascular age (vascular_age in years) for a date range — Oura-unique signal with no Fitbit equivalent.
Full description
Per-day cardiovascular age over a date range.
Returns Oura's estimated vascular age (in years) per day. Oura derives this
from heart-health signals; it is an Oura-unique signal with no Fitbit
equivalent. Cadence is slow (the value updates roughly weekly), so daily
rows may repeat across consecutive days.
Parameters:
start_date (str, required): Inclusive start date (YYYY-MM-DD).
end_date (str, required): Inclusive end date (YYYY-MM-DD).
Returns:
GetCardiovascularAgeResult with `days`, `missing_dates`.
Errors:
UNAUTHORIZED: Could not authenticate.
VALIDATION_ERROR: Invalid date format or start_date > end_date. | Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Inclusive start date (YYYY-MM-DD) |
end_date | string | Yes | Inclusive end date (YYYY-MM-DD) |
Parameter schema (JSON)
{
"description": "Parameters for get_cardiovascular_age",
"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"
}
},
"required": [
"start_date",
"end_date"
],
"title": "GetCardiovascularAgeParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"CardiovascularAgeDay": {
"description": "One day of cardiovascular age data.",
"properties": {
"day": {
"title": "Day",
"type": "string"
},
"vascular_age": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Estimated vascular age (years)",
"title": "Vascular Age"
}
},
"required": [
"day"
],
"title": "CardiovascularAgeDay",
"type": "object"
}
},
"description": "Result from get_cardiovascular_age",
"properties": {
"days": {
"items": {
"$ref": "#/$defs/CardiovascularAgeDay"
},
"title": "Days",
"type": "array"
},
"missing_dates": {
"items": {
"type": "string"
},
"title": "Missing Dates",
"type": "array"
}
},
"required": [
"days",
"missing_dates"
],
"title": "GetCardiovascularAgeResult",
"type": "object"
} # get_daily_summary read
Fetch Oura daily scores (sleep, readiness, activity) and aggregate metrics (stress, SpO2) for a date range — the headline per-day numbers.
Full description
Fetch per-day aggregates for a date range, optionally including baselines.
This retrieves daily summaries from Oura for sleep, readiness, activity,
stress, and SpO2 metrics.
Parameters:
start_date (str, required): Start date in YYYY-MM-DD format
end_date (str, required): End date in YYYY-MM-DD format
metrics (array, required): Metrics to retrieve:
- "sleep": Sleep duration, efficiency, stages
- "readiness": Readiness score and contributors
- "activity": Steps, calories, activity minutes
- "stress": Stress levels and recovery
- "spo2": Blood oxygen saturation
include_baseline (bool, optional): Include baseline calculations. Default: true
baseline_window_days (int, optional): Days for baseline window (min 7). Default: 14
Returns:
GetDailySummaryResult with:
- days: Array of daily summary objects (days with no data are omitted)
- baseline: Optional baseline statistics
Errors:
UNAUTHORIZED: Could not authenticate
VALIDATION_ERROR: Invalid date range
DATA_GAP: No data available for requested dates | 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<"sleep" | "readiness" | "activity" | "stress" | "spo2"> | Yes | Metrics to retrieve (sleep, readiness, activity, stress, spo2) |
include_baseline | boolean | No | Include baseline calculations Default: true |
baseline_window_days | integer | No | Days for baseline window Default: 14 |
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 (sleep, readiness, activity, stress, spo2)",
"items": {
"enum": [
"sleep",
"readiness",
"activity",
"stress",
"spo2"
],
"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"
}
},
"required": [
"start_date",
"end_date",
"metrics"
],
"title": "GetDailySummaryParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"Baseline": {
"description": "Baseline statistics",
"properties": {
"window_days": {
"description": "Number of days in baseline window",
"title": "Window Days",
"type": "integer"
},
"metrics": {
"additionalProperties": {
"type": "number"
},
"description": "Baseline values for each metric",
"title": "Metrics",
"type": "object"
}
},
"required": [
"window_days",
"metrics"
],
"title": "Baseline",
"type": "object"
},
"DailyActivity": {
"description": "Daily activity summary",
"properties": {
"score": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Activity score (0-100)",
"title": "Score"
},
"active_calories": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Active calories burned",
"title": "Active Calories"
},
"total_calories": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Total calories burned",
"title": "Total Calories"
},
"steps": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Daily step count",
"title": "Steps"
},
"equivalent_walking_distance_m": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Equivalent walking distance in meters",
"title": "Equivalent Walking Distance M"
},
"high_activity_min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "High activity minutes",
"title": "High Activity Min"
},
"medium_activity_min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Medium activity minutes",
"title": "Medium Activity Min"
},
"low_activity_min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Low activity minutes",
"title": "Low Activity Min"
},
"sedentary_min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Sedentary minutes",
"title": "Sedentary Min"
},
"resting_time_min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Resting time in minutes",
"title": "Resting Time Min"
},
"met_min_inactive": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "MET minutes while inactive",
"title": "Met Min Inactive"
},
"met_min_low": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "MET minutes during low activity",
"title": "Met Min Low"
},
"met_min_medium": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "MET minutes during medium activity",
"title": "Met Min Medium"
},
"met_min_high": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "MET minutes during high activity",
"title": "Met Min High"
}
},
"title": "DailyActivity",
"type": "object"
},
"DailyReadiness": {
"description": "Daily readiness summary",
"properties": {
"score": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Readiness score (0-100)",
"title": "Score"
},
"temperature_deviation": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Body temperature deviation from baseline",
"title": "Temperature Deviation"
},
"activity_balance": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Activity balance contributor",
"title": "Activity Balance"
},
"body_temperature": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Body temperature contributor",
"title": "Body Temperature"
},
"hrv_balance": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "HRV balance contributor",
"title": "Hrv Balance"
},
"previous_day_activity": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Previous day activity contributor",
"title": "Previous Day Activity"
},
"previous_night": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Previous night contributor",
"title": "Previous Night"
},
"recovery_index": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Recovery index contributor",
"title": "Recovery Index"
},
"resting_heart_rate": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Resting heart rate contributor",
"title": "Resting Heart Rate"
},
"sleep_balance": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Sleep balance contributor",
"title": "Sleep Balance"
}
},
"title": "DailyReadiness",
"type": "object"
},
"DailySleep": {
"description": "Daily sleep summary with scores from daily_sleep endpoint",
"properties": {
"score": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Overall sleep score (0-100)",
"title": "Score"
},
"contributors": {
"anyOf": [
{
"$ref": "#/$defs/SleepContributors"
},
{
"type": "null"
}
],
"default": null,
"description": "Sleep contributor scores"
},
"primary_session_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ID of primary (longest long_sleep) session",
"title": "Primary Session Id"
}
},
"title": "DailySleep",
"type": "object"
},
"DailySpo2": {
"description": "Daily SpO2 summary",
"properties": {
"spo2_average_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Average blood oxygen percentage",
"title": "Spo2 Average Pct"
},
"breathing_disturbance_index": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Breathing disturbance index",
"title": "Breathing Disturbance Index"
}
},
"title": "DailySpo2",
"type": "object"
},
"DailyStress": {
"description": "Daily stress summary",
"properties": {
"day_summary": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stress level summary (restored, normal, stressful, high)",
"title": "Day Summary"
},
"stress_high_min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Minutes in high stress",
"title": "Stress High Min"
},
"recovery_high_min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Minutes in high recovery",
"title": "Recovery High Min"
}
},
"title": "DailyStress",
"type": "object"
},
"DaySummary": {
"description": "Complete daily summary",
"properties": {
"date": {
"description": "Date in YYYY-MM-DD format",
"title": "Date",
"type": "string"
},
"sleep": {
"anyOf": [
{
"$ref": "#/$defs/DailySleep"
},
{
"type": "null"
}
],
"default": null,
"description": "Daily sleep data"
},
"readiness": {
"anyOf": [
{
"$ref": "#/$defs/DailyReadiness"
},
{
"type": "null"
}
],
"default": null,
"description": "Daily readiness data"
},
"activity": {
"anyOf": [
{
"$ref": "#/$defs/DailyActivity"
},
{
"type": "null"
}
],
"default": null,
"description": "Daily activity data"
},
"stress": {
"anyOf": [
{
"$ref": "#/$defs/DailyStress"
},
{
"type": "null"
}
],
"default": null,
"description": "Daily stress data"
},
"spo2": {
"anyOf": [
{
"$ref": "#/$defs/DailySpo2"
},
{
"type": "null"
}
],
"default": null,
"description": "Daily SpO2 data"
}
},
"required": [
"date"
],
"title": "DaySummary",
"type": "object"
},
"SleepContributors": {
"description": "Sleep contributor scores (0-100 scale)",
"properties": {
"total_sleep": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Score for total sleep duration (0-100)",
"title": "Total Sleep"
},
"efficiency": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Score for sleep efficiency (0-100)",
"title": "Efficiency"
},
"restfulness": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Score for restfulness/movement (0-100)",
"title": "Restfulness"
},
"rem_sleep": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Score for REM sleep amount (0-100)",
"title": "Rem Sleep"
},
"deep_sleep": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Score for deep sleep amount (0-100)",
"title": "Deep Sleep"
},
"latency": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Score for time to fall asleep (0-100)",
"title": "Latency"
},
"timing": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Score for sleep timing alignment (0-100)",
"title": "Timing"
}
},
"title": "SleepContributors",
"type": "object"
}
},
"description": "Result from get_daily_summary",
"properties": {
"days": {
"description": "Daily summary data (days with no data are omitted)",
"items": {
"$ref": "#/$defs/DaySummary"
},
"title": "Days",
"type": "array"
},
"baseline": {
"anyOf": [
{
"$ref": "#/$defs/Baseline"
},
{
"type": "null"
}
],
"default": null,
"description": "Baseline statistics if requested"
},
"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_intraday read
Return intraday data for heart rate or activity with summary statistics.
Full description
Return intraday data for heart rate or activity with summary statistics.
By default returns summary only. Use include_time_series=true for
downsampled 15-minute interval data.
Parameters:
resource (str, required): Type of intraday data:
- "heart_rate": Heart rate measurements
- "steps": Step counts (from daily activity 5-min intervals)
date (str, required): Date in YYYY-MM-DD format
start_time (str, optional): Start time filter (HH:MM)
end_time (str, optional): End time filter (HH:MM)
include_time_series (bool, optional): Include downsampled time series.
Default: false (returns summary only)
Returns:
GetIntradayResult with:
- resource: The requested resource type
- date: The requested date
- summary: Statistics (min, max, avg, count, by_source for HR)
- time_series: Downsampled data (only if include_time_series=true)
Errors:
UNAUTHORIZED: Could not authenticate
INSUFFICIENT_SCOPE: Missing required OAuth scope
DATA_GAP: No intraday data for the specified date | Parameter | Type | Required | Description |
|---|---|---|---|
resource | "heart_rate" | "steps" | Yes | Intraday resource type |
date | string | Yes | Date (YYYY-MM-DD) |
start_time | string | null | No | Start time (HH:MM) - optional filter |
end_time | string | null | No | End time (HH:MM) - optional filter |
include_time_series | boolean | No | Include time-series data (downsampled to 15-min intervals). Default returns summary only. Default: false |
Parameter schema (JSON)
{
"description": "Parameters for get_intraday",
"properties": {
"resource": {
"description": "Intraday resource type",
"enum": [
"heart_rate",
"steps"
],
"title": "Resource",
"type": "string"
},
"date": {
"description": "Date (YYYY-MM-DD)",
"title": "Date",
"type": "string"
},
"start_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Start time (HH:MM) - optional filter",
"title": "Start Time"
},
"end_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "End time (HH:MM) - optional filter",
"title": "End Time"
},
"include_time_series": {
"default": false,
"description": "Include time-series data (downsampled to 15-min intervals). Default returns summary only.",
"title": "Include Time Series",
"type": "boolean"
}
},
"required": [
"resource",
"date"
],
"title": "GetIntradayParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"DownsampledPoint": {
"description": "Downsampled time series point (15-min interval)",
"properties": {
"time": {
"description": "Time in HH:MM format",
"title": "Time",
"type": "string"
},
"value": {
"description": "Average value for this interval",
"title": "Value",
"type": "number"
},
"source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Dominant source for this interval (HR only)",
"title": "Source"
}
},
"required": [
"time",
"value"
],
"title": "DownsampledPoint",
"type": "object"
},
"HRSourceBreakdown": {
"description": "Heart rate breakdown by source",
"properties": {
"source": {
"description": "Data source (awake, rest, sleep, workout)",
"title": "Source",
"type": "string"
},
"count": {
"description": "Number of readings from this source",
"title": "Count",
"type": "integer"
},
"avg_bpm": {
"description": "Average heart rate from this source",
"title": "Avg Bpm",
"type": "number"
},
"min_bpm": {
"description": "Minimum heart rate from this source",
"title": "Min Bpm",
"type": "integer"
},
"max_bpm": {
"description": "Maximum heart rate from this source",
"title": "Max Bpm",
"type": "integer"
}
},
"required": [
"source",
"count",
"avg_bpm",
"min_bpm",
"max_bpm"
],
"title": "HRSourceBreakdown",
"type": "object"
},
"IntradaySummary": {
"description": "Summary statistics for intraday data",
"properties": {
"data_points": {
"description": "Total number of data points",
"title": "Data Points",
"type": "integer"
},
"min_value": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum value",
"title": "Min Value"
},
"max_value": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum value",
"title": "Max Value"
},
"avg_value": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Average value",
"title": "Avg Value"
},
"by_source": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/HRSourceBreakdown"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Breakdown by data source (HR only)",
"title": "By Source"
}
},
"required": [
"data_points"
],
"title": "IntradaySummary",
"type": "object"
}
},
"description": "Result from get_intraday",
"properties": {
"resource": {
"description": "Resource type retrieved",
"title": "Resource",
"type": "string"
},
"date": {
"description": "Date of data",
"title": "Date",
"type": "string"
},
"summary": {
"$ref": "#/$defs/IntradaySummary",
"description": "Summary statistics"
},
"time_series": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/DownsampledPoint"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Downsampled time series (15-min intervals, only if include_time_series=true)",
"title": "Time Series"
}
},
"required": [
"resource",
"date",
"summary"
],
"title": "GetIntradayResult",
"type": "object"
} # get_overnight_hrv read
Fetch Oura nightly average HRV (RMSSD) for a date range with optional rolling baseline + Z-score; supports 5-min intraday samples (Oura-unique).
Full description
Per-night heart rate variability (RMSSD) for a date range.
Reads the nightly `average_hrv` from the primary `long_sleep` session per
day (naps and short rest sessions are excluded for a cleaner signal). 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`. When `include_intraday=true`, also
returns Oura's 5-minute granularity HRV samples — a capability Fitbit's
equivalent tool cannot match.
Parameters:
start_date (str, required): Inclusive start date (YYYY-MM-DD).
end_date (str, required): Inclusive end date (YYYY-MM-DD).
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.
include_intraday (bool, optional): Include 5-min granularity HRV samples per night. Default false.
Returns:
GetOvernightHrvResult with `nights`, `baseline`, `missing_dates`, `notes`.
Errors:
UNAUTHORIZED: Could not authenticate.
VALIDATION_ERROR: Invalid date format or start_date > end_date. | Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Inclusive start date (YYYY-MM-DD) |
end_date | string | Yes | Inclusive end date (YYYY-MM-DD) |
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 |
include_intraday | boolean | No | Oura-unique: include 5-minute granularity HRV samples per night. Default false (nightly average only). Default: false |
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)",
"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"
},
"include_intraday": {
"default": false,
"description": "Oura-unique: include 5-minute granularity HRV samples per night. Default false (nightly average only).",
"title": "Include Intraday",
"type": "boolean"
}
},
"required": [
"start_date",
"end_date"
],
"title": "GetOvernightHrvParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"HrvIntradaySample": {
"description": "One 5-minute granularity HRV sample within a sleep session.",
"properties": {
"timestamp": {
"description": "ISO timestamp of the sample",
"title": "Timestamp",
"type": "string"
},
"value": {
"description": "RMSSD (ms) for this 5-min interval",
"title": "Value",
"type": "number"
}
},
"required": [
"timestamp",
"value"
],
"title": "HrvIntradaySample",
"type": "object"
},
"OuraHrvBaseline": {
"description": "Rolling baseline over the preceding window.",
"properties": {
"mean_average_hrv": {
"title": "Mean Average Hrv",
"type": "number"
},
"stdev_average_hrv": {
"title": "Stdev Average Hrv",
"type": "number"
},
"n_nights_in_baseline": {
"title": "N Nights In Baseline",
"type": "integer"
},
"window_days": {
"title": "Window Days",
"type": "integer"
}
},
"required": [
"mean_average_hrv",
"stdev_average_hrv",
"n_nights_in_baseline",
"window_days"
],
"title": "OuraHrvBaseline",
"type": "object"
},
"OuraHrvNight": {
"description": "One night of HRV data from the /sleep endpoint's primary long_sleep session.",
"properties": {
"date": {
"description": "Day-of-night (YYYY-MM-DD)",
"title": "Date",
"type": "string"
},
"average_hrv": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Nightly average RMSSD (ms)",
"title": "Average Hrv"
},
"delta_vs_baseline": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "average_hrv minus baseline mean; only with baseline established",
"title": "Delta Vs Baseline"
},
"z_score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "(average_hrv - mean) / stdev; only with baseline established",
"title": "Z Score"
},
"hrv_samples": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/HrvIntradaySample"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "5-min granularity samples; only when include_intraday=true",
"title": "Hrv Samples"
}
},
"required": [
"date"
],
"title": "OuraHrvNight",
"type": "object"
}
},
"description": "Result from get_overnight_hrv",
"properties": {
"nights": {
"items": {
"$ref": "#/$defs/OuraHrvNight"
},
"title": "Nights",
"type": "array"
},
"baseline": {
"anyOf": [
{
"$ref": "#/$defs/OuraHrvBaseline"
},
{
"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_permissions read
Return the OAuth scopes currently granted for this Oura connection.
Full description
Return OAuth scopes currently granted for this Oura connection.
Uses token exchange with include_scopes=true to retrieve scopes
without making external API calls to Oura. This is more efficient
than calling the ring_configuration API.
Parameters:
None - This tool takes no parameters.
Returns:
GetPermissionsResult with:
- scopes: List of granted scope codes (e.g., ["daily", "heartrate", "personal"])
- scope_details: Array of detailed scope information with:
- code: Scope code
- name: Human-readable name
- description: What this scope provides access to
Common scopes:
- daily: Sleep, activity, and readiness scores
- heartrate: Heart rate time-series data
- personal: User profile and ring configuration
- spo2: Blood oxygen measurements (Gen 3+ rings)
- workout: Workout sessions
- session: Mindfulness sessions
- tag: User-created tags
Errors:
ProviderError: User has not connected Oura or token is invalid/expired No parameters.
Parameter schema (JSON)
{
"description": "Parameters for get_permissions - none required",
"properties": {},
"title": "GetPermissionsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"ScopeDetail": {
"description": "Detailed information about an OAuth scope",
"properties": {
"code": {
"description": "Scope code (e.g., 'daily')",
"title": "Code",
"type": "string"
},
"name": {
"description": "Human-readable name",
"title": "Name",
"type": "string"
},
"description": {
"description": "What this scope provides access to",
"title": "Description",
"type": "string"
}
},
"required": [
"code",
"name",
"description"
],
"title": "ScopeDetail",
"type": "object"
}
},
"description": "Result from get_permissions",
"properties": {
"scopes": {
"description": "List of granted scope codes",
"items": {
"type": "string"
},
"title": "Scopes",
"type": "array"
},
"scope_details": {
"description": "Detailed scope information",
"items": {
"$ref": "#/$defs/ScopeDetail"
},
"title": "Scope Details",
"type": "array"
}
},
"required": [
"scopes",
"scope_details"
],
"title": "GetPermissionsResult",
"type": "object"
} # get_readiness_panel read
Explain what is driving Oura readiness — fuse the readiness score, its 8 contributors (hrv balance, body temperature, recovery index, sleep balance, etc.), raw HRV/breathing/temp/RHR metrics, and derived recovery flags into a per-night panel.
Full description
Multi-signal readiness panel for a date range.
Joins per-day data from `/daily_readiness` + (when `include_sleep_detail=true`)
`/daily_sleep` and `/sleep` into a fused per-night object containing Oura's
native readiness/sleep scores, the 8 readiness contributors, raw HRV /
breathing / temperature / lowest-HR metrics, and a list of derived flags
(low_hrv, high_rhr, cardiovascular_strain, elevated_temp_and_breathing,
fragmented_sleep, low_deep_sleep, low_rem) that mirror
`my_fitbit_data-get_sleep_health_panel` for cross-toolkit consistency.
Z-scores for HRV / breathing / RHR are computed inline against the
preceding `baseline_days` window of `/sleep` data. Skin-temperature
deviation comes pre-baselined from `/daily_readiness`.
Parameters:
start_date (str, required): Inclusive start date (YYYY-MM-DD).
end_date (str, required): Inclusive end date (YYYY-MM-DD).
baseline_days (int, optional): Window for HRV/breathing/RHR baselines (7-90). Default 28.
include_sleep_detail (bool, optional): Include daily_sleep + /sleep endpoints
for sleep_score, raw_metrics, and architecture-derived flags. Default true.
Returns:
GetReadinessPanelResult with `nights`, `missing_dates`, `notes`.
Errors:
UNAUTHORIZED: Could not authenticate.
VALIDATION_ERROR: Invalid date format or start_date > end_date. | Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Inclusive start date (YYYY-MM-DD) |
end_date | string | Yes | Inclusive end date (YYYY-MM-DD) |
baseline_days | integer | No | Window size for HRV/RHR/breathing baselines (7-90). Default: 28 |
include_sleep_detail | boolean | No | If true, also fetch /daily_sleep + /sleep endpoints to populate sleep_score, raw_metrics, and architecture-derived flags. Default: true |
Parameter schema (JSON)
{
"description": "Parameters for get_readiness_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)",
"title": "End Date",
"type": "string"
},
"baseline_days": {
"default": 28,
"description": "Window size for HRV/RHR/breathing baselines (7-90).",
"maximum": 90,
"minimum": 7,
"title": "Baseline Days",
"type": "integer"
},
"include_sleep_detail": {
"default": true,
"description": "If true, also fetch /daily_sleep + /sleep endpoints to populate sleep_score, raw_metrics, and architecture-derived flags.",
"title": "Include Sleep Detail",
"type": "boolean"
}
},
"required": [
"start_date",
"end_date"
],
"title": "GetReadinessPanelParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"ReadinessContributors": {
"description": "Oura's 8 daily_readiness contributors (each 0-100).",
"properties": {
"activity_balance": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Activity Balance"
},
"body_temperature": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Body Temperature"
},
"hrv_balance": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Hrv Balance"
},
"previous_day_activity": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Previous Day Activity"
},
"previous_night": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Previous Night"
},
"recovery_index": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Recovery Index"
},
"resting_heart_rate": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Resting Heart Rate"
},
"sleep_balance": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sleep Balance"
}
},
"title": "ReadinessContributors",
"type": "object"
},
"ReadinessPanelFlag": {
"description": "A computed flag for one night, mirroring my_fitbit_data-get_sleep_health_panel.",
"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": "ReadinessPanelFlag",
"type": "object"
},
"ReadinessPanelNight": {
"description": "One night's fused readiness/sleep signals + computed flags.",
"properties": {
"date": {
"title": "Date",
"type": "string"
},
"readiness_score": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Oura's 0-100 daily readiness score",
"title": "Readiness Score"
},
"sleep_score": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Oura's 0-100 daily sleep score (only when include_sleep_detail=true)",
"title": "Sleep Score"
},
"contributors": {
"$ref": "#/$defs/ReadinessContributors"
},
"raw_metrics": {
"anyOf": [
{
"$ref": "#/$defs/ReadinessRawMetrics"
},
{
"type": "null"
}
],
"default": null
},
"hrv_z": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "z-score of average_hrv vs preceding baseline_days window",
"title": "Hrv Z"
},
"rhr_z": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "z-score of lowest_heart_rate vs preceding baseline_days window",
"title": "Rhr Z"
},
"breathing_z": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "z-score of average_breath_per_min vs preceding baseline_days window",
"title": "Breathing Z"
},
"flags": {
"items": {
"$ref": "#/$defs/ReadinessPanelFlag"
},
"title": "Flags",
"type": "array"
}
},
"required": [
"date",
"contributors",
"flags"
],
"title": "ReadinessPanelNight",
"type": "object"
},
"ReadinessRawMetrics": {
"description": "Raw underlying metrics (only populated when include_sleep_detail=true).",
"properties": {
"average_hrv": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Nightly average RMSSD (ms) from /sleep endpoint",
"title": "Average Hrv"
},
"average_breath_per_min": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Nightly average breathing rate (breaths/min)",
"title": "Average Breath Per Min"
},
"lowest_heart_rate": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Lowest HR during sleep (bpm) — used as RHR proxy",
"title": "Lowest Heart Rate"
},
"temperature_deviation": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Nightly skin temp deviation from personal baseline (°C)",
"title": "Temperature Deviation"
},
"deep_sleep_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Deep sleep as fraction of total sleep",
"title": "Deep Sleep Pct"
},
"rem_sleep_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "REM sleep as fraction of total sleep",
"title": "Rem Sleep Pct"
},
"efficiency": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Sleep efficiency (0.0-1.0)",
"title": "Efficiency"
},
"restless_periods": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Count of restless periods during sleep",
"title": "Restless Periods"
}
},
"title": "ReadinessRawMetrics",
"type": "object"
}
},
"description": "Result from get_readiness_panel",
"properties": {
"nights": {
"items": {
"$ref": "#/$defs/ReadinessPanelNight"
},
"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": "GetReadinessPanelResult",
"type": "object"
} # get_resilience read
Fetch Oura daily resilience level (long-term stress recovery capacity) for a date range — Oura-unique signal with no Fitbit equivalent.
Full description
Per-day resilience level over a date range.
Resilience is Oura's long-term stress-recovery capacity signal, returned as
a categorical level (limited / adequate / solid / strong / exceptional)
plus contributor scores (sleep_recovery, daytime_recovery, stress). This
is an Oura-unique signal — no Fitbit equivalent exists.
Parameters:
start_date (str, required): Inclusive start date (YYYY-MM-DD).
end_date (str, required): Inclusive end date (YYYY-MM-DD).
Returns:
GetResilienceResult with `days`, `missing_dates`.
Errors:
UNAUTHORIZED: Could not authenticate.
VALIDATION_ERROR: Invalid date format or start_date > end_date. | Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Inclusive start date (YYYY-MM-DD) |
end_date | string | Yes | Inclusive end date (YYYY-MM-DD) |
Parameter schema (JSON)
{
"description": "Parameters for get_resilience",
"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"
}
},
"required": [
"start_date",
"end_date"
],
"title": "GetResilienceParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"ResilienceContributors": {
"description": "Resilience contributors (each 0-100; Oura returns these as floats).",
"properties": {
"sleep_recovery": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Sleep Recovery"
},
"daytime_recovery": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Daytime Recovery"
},
"stress": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Stress"
}
},
"title": "ResilienceContributors",
"type": "object"
},
"ResilienceDay": {
"description": "One day of resilience data.",
"properties": {
"day": {
"title": "Day",
"type": "string"
},
"level": {
"anyOf": [
{
"enum": [
"limited",
"adequate",
"solid",
"strong",
"exceptional"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Categorical resilience level",
"title": "Level"
},
"contributors": {
"anyOf": [
{
"$ref": "#/$defs/ResilienceContributors"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"day"
],
"title": "ResilienceDay",
"type": "object"
}
},
"description": "Result from get_resilience",
"properties": {
"days": {
"items": {
"$ref": "#/$defs/ResilienceDay"
},
"title": "Days",
"type": "array"
},
"missing_dates": {
"items": {
"type": "string"
},
"title": "Missing Dates",
"type": "array"
}
},
"required": [
"days",
"missing_dates"
],
"title": "GetResilienceResult",
"type": "object"
} # get_skin_temp_variation read
Fetch Oura nightly skin-temperature deviation from personal baseline (already server-side baselined) for a date range.
Full description
Per-night skin temperature deviation (Δ from the user's personal baseline)
for a date range.
The value Oura returns is already a relative delta in °C (the ring computes
each user's baseline server-side from their first weeks of wear). No
additional baseline is layered here. Each night is flagged elevated /
depressed / normal using thresholds matching `my_fitbit_data-get_skin_temp_variation`
for cross-toolkit consistency.
Parameters:
start_date (str, required): Inclusive start date (YYYY-MM-DD).
end_date (str, required): Inclusive end date (YYYY-MM-DD).
Returns:
GetSkinTempVariationResult with `nights`, `missing_dates`, `notes`.
Errors:
UNAUTHORIZED: Could not authenticate.
VALIDATION_ERROR: Invalid date format or start_date > end_date. | Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Inclusive start date (YYYY-MM-DD) |
end_date | string | Yes | Inclusive end date (YYYY-MM-DD) |
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)",
"title": "End Date",
"type": "string"
}
},
"required": [
"start_date",
"end_date"
],
"title": "GetSkinTempVariationParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"OuraSkinTempNight": {
"description": "One night of skin temperature variation. Oura already returns the value as a delta from\nthe user's personal baseline (computed server-side), so no additional baseline is layered here.",
"properties": {
"date": {
"description": "Day-of-night (YYYY-MM-DD)",
"title": "Date",
"type": "string"
},
"temperature_deviation": {
"description": "Nightly deviation from personal baseline (°C, signed)",
"title": "Temperature Deviation",
"type": "number"
},
"temperature_trend_deviation": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Longer-term trend deviation from baseline (°C, signed)",
"title": "Temperature Trend Deviation"
},
"flag": {
"description": "elevated if dev > +0.5°C, depressed if < -0.3°C, else normal (thresholds match Fitbit equivalent)",
"enum": [
"elevated",
"depressed",
"normal"
],
"title": "Flag",
"type": "string"
}
},
"required": [
"date",
"temperature_deviation",
"flag"
],
"title": "OuraSkinTempNight",
"type": "object"
}
},
"description": "Result from get_skin_temp_variation",
"properties": {
"nights": {
"items": {
"$ref": "#/$defs/OuraSkinTempNight"
},
"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": "GetSkinTempVariationResult",
"type": "object"
} # get_sleep_sessions read
Get detailed sleep session data for a date range.
Full description
Get detailed sleep session data for a date range.
This retrieves session-level sleep data from the /v2/usercollection/sleep
endpoint, which includes actual durations, HR, HRV, and time series data.
Parameters:
start_date (str, required): Inclusive start date (YYYY-MM-DD)
end_date (str, required): Inclusive end date (YYYY-MM-DD). Same as start_date for single day.
include_time_series (bool, optional): Include HR/HRV time-series data,
downsampled to 15-minute intervals. Default: false
Returns:
GetSleepSessionsResult with:
- sessions: Array of sleep session objects with:
- id, date, type (long_sleep, late_nap, rest, nap)
- bedtime_start, bedtime_end
- Durations in seconds and hours (total, deep, light, rem, awake, latency)
- Metrics (efficiency, restless_periods, HR, HRV, breath rate)
- time_series (if include_time_series=true)
- summary: Statistics (total_sessions, avg_duration_hours, avg_efficiency)
Errors:
UNAUTHORIZED: Could not authenticate
VALIDATION_ERROR: Invalid date format or start_date > end_date
DATA_GAP: No sleep data for the specified 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) |
include_time_series | boolean | No | Include HR/HRV time-series data (downsampled to 15-min intervals) Default: false |
Parameter schema (JSON)
{
"description": "Parameters for get_sleep_sessions",
"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_time_series": {
"default": false,
"description": "Include HR/HRV time-series data (downsampled to 15-min intervals)",
"title": "Include Time Series",
"type": "boolean"
}
},
"required": [
"start_date",
"end_date"
],
"title": "GetSleepSessionsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"SleepSession": {
"description": "Detailed sleep session data from /v2/usercollection/sleep endpoint",
"properties": {
"id": {
"description": "Unique sleep session ID",
"title": "Id",
"type": "string"
},
"date": {
"description": "Date the sleep session is attributed to (YYYY-MM-DD)",
"title": "Date",
"type": "string"
},
"type": {
"description": "Sleep type (long_sleep, late_nap, rest, nap)",
"title": "Type",
"type": "string"
},
"bedtime_start": {
"description": "Bedtime start timestamp (ISO8601)",
"title": "Bedtime Start",
"type": "string"
},
"bedtime_end": {
"description": "Bedtime end timestamp (ISO8601)",
"title": "Bedtime End",
"type": "string"
},
"total_sleep_duration_sec": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Total sleep in seconds",
"title": "Total Sleep Duration Sec"
},
"total_sleep_duration_hours": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Total sleep in hours",
"title": "Total Sleep Duration Hours"
},
"deep_sleep_sec": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Deep sleep in seconds",
"title": "Deep Sleep Sec"
},
"deep_sleep_hours": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Deep sleep in hours",
"title": "Deep Sleep Hours"
},
"light_sleep_sec": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Light sleep in seconds",
"title": "Light Sleep Sec"
},
"light_sleep_hours": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Light sleep in hours",
"title": "Light Sleep Hours"
},
"rem_sleep_sec": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "REM sleep in seconds",
"title": "Rem Sleep Sec"
},
"rem_sleep_hours": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "REM sleep in hours",
"title": "Rem Sleep Hours"
},
"awake_sec": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Awake time in seconds",
"title": "Awake Sec"
},
"awake_min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Awake time in minutes",
"title": "Awake Min"
},
"latency_sec": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Sleep latency in seconds",
"title": "Latency Sec"
},
"latency_min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Sleep latency in minutes",
"title": "Latency Min"
},
"efficiency": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Sleep efficiency percentage",
"title": "Efficiency"
},
"restless_periods": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Number of restless periods",
"title": "Restless Periods"
},
"average_heart_rate": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Average heart rate during sleep",
"title": "Average Heart Rate"
},
"lowest_heart_rate": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Lowest heart rate during sleep",
"title": "Lowest Heart Rate"
},
"average_hrv": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Average HRV during sleep",
"title": "Average Hrv"
},
"average_breath_rate": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Average breathing rate",
"title": "Average Breath Rate"
},
"time_series": {
"anyOf": [
{
"$ref": "#/$defs/SleepTimeSeries"
},
{
"type": "null"
}
],
"default": null,
"description": "Downsampled time series data"
}
},
"required": [
"id",
"date",
"type",
"bedtime_start",
"bedtime_end"
],
"title": "SleepSession",
"type": "object"
},
"SleepSessionsSummary": {
"description": "Summary statistics for sleep sessions",
"properties": {
"total_sessions": {
"description": "Total number of sessions in the response",
"title": "Total Sessions",
"type": "integer"
},
"avg_duration_hours": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Average sleep duration in hours",
"title": "Avg Duration Hours"
},
"avg_efficiency": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Average sleep efficiency percentage",
"title": "Avg Efficiency"
}
},
"required": [
"total_sessions"
],
"title": "SleepSessionsSummary",
"type": "object"
},
"SleepTimeSeries": {
"description": "Downsampled time series data for a sleep session",
"properties": {
"interval_minutes": {
"default": 15,
"description": "Time interval between samples in minutes",
"title": "Interval Minutes",
"type": "integer"
},
"samples": {
"description": "Time series samples",
"items": {
"$ref": "#/$defs/TimeSeriesSample"
},
"title": "Samples",
"type": "array"
}
},
"title": "SleepTimeSeries",
"type": "object"
},
"TimeSeriesSample": {
"description": "Downsampled time series sample during sleep",
"properties": {
"time": {
"description": "Time in HH:MM format",
"title": "Time",
"type": "string"
},
"minutes_from_bedtime": {
"description": "Minutes elapsed since bedtime",
"title": "Minutes From Bedtime",
"type": "integer"
},
"heart_rate": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Heart rate in bpm",
"title": "Heart Rate"
},
"hrv": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Heart rate variability",
"title": "Hrv"
},
"phase": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Sleep phase (deep, light, rem, awake)",
"title": "Phase"
}
},
"required": [
"time",
"minutes_from_bedtime"
],
"title": "TimeSeriesSample",
"type": "object"
}
},
"description": "Result from get_sleep_sessions",
"properties": {
"sessions": {
"description": "Sleep sessions for the date range",
"items": {
"$ref": "#/$defs/SleepSession"
},
"title": "Sessions",
"type": "array"
},
"summary": {
"$ref": "#/$defs/SleepSessionsSummary",
"description": "Summary statistics"
}
},
"required": [
"sessions",
"summary"
],
"title": "GetSleepSessionsResult",
"type": "object"
} # get_spo2 read
Fetch Oura daily average overnight SpO2 (%) plus Breathing Disturbance Index (BDI) for sleep apnea screening — Oura-unique signal.
Full description
Per-day average overnight SpO2 + Breathing Disturbance Index (BDI).
BDI is Oura's index (0-100) of breathing disturbances during sleep, derived
from SpO2 drops. Higher = more disturbed; persistently elevated values are
a screening signal for sleep apnea. This pairing of average overnight SpO2
with BDI is Oura-unique — no Fitbit equivalent exists.
BDI flag thresholds: elevated if BDI > 60, watch if 40-60, else normal.
Parameters:
start_date (str, required): Inclusive start date (YYYY-MM-DD).
end_date (str, required): Inclusive end date (YYYY-MM-DD).
Returns:
GetSpo2Result with `days`, `missing_dates`.
Errors:
UNAUTHORIZED: Could not authenticate.
VALIDATION_ERROR: Invalid date format or start_date > end_date. | Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Inclusive start date (YYYY-MM-DD) |
end_date | string | Yes | Inclusive end date (YYYY-MM-DD) |
Parameter schema (JSON)
{
"description": "Parameters for get_spo2",
"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"
}
},
"required": [
"start_date",
"end_date"
],
"title": "GetSpo2Params",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"Spo2Day": {
"description": "One day of SpO2 + breathing disturbance index.",
"properties": {
"day": {
"title": "Day",
"type": "string"
},
"spo2_average_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Average overnight SpO2 (%)",
"title": "Spo2 Average Pct"
},
"breathing_disturbance_index": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Breathing Disturbance Index (BDI), 0-100, higher = more disturbed breathing during sleep",
"title": "Breathing Disturbance Index"
},
"bdi_flag": {
"description": "elevated if BDI > 60, watch if 40-60, else normal",
"enum": [
"normal",
"watch",
"elevated"
],
"title": "Bdi Flag",
"type": "string"
}
},
"required": [
"day",
"bdi_flag"
],
"title": "Spo2Day",
"type": "object"
}
},
"description": "Result from get_spo2",
"properties": {
"days": {
"items": {
"$ref": "#/$defs/Spo2Day"
},
"title": "Days",
"type": "array"
},
"missing_dates": {
"items": {
"type": "string"
},
"title": "Missing Dates",
"type": "array"
}
},
"required": [
"days",
"missing_dates"
],
"title": "GetSpo2Result",
"type": "object"
} # get_stress read
Fetch Oura daily stress and recovery summary (high-stress and high-recovery minutes plus categorical day_summary) for a date range — Oura-unique signal.
Full description
Per-day stress + recovery summary over a date range.
Returns Oura's daily stress signal: minutes spent in high stress, minutes
in high recovery, and a categorical day_summary (restored / normal /
stressful). This is an Oura-unique signal with no Fitbit equivalent.
Parameters:
start_date (str, required): Inclusive start date (YYYY-MM-DD).
end_date (str, required): Inclusive end date (YYYY-MM-DD).
Returns:
GetStressResult with `days`, `missing_dates`.
Errors:
UNAUTHORIZED: Could not authenticate.
VALIDATION_ERROR: Invalid date format or start_date > end_date. | Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Inclusive start date (YYYY-MM-DD) |
end_date | string | Yes | Inclusive end date (YYYY-MM-DD) |
Parameter schema (JSON)
{
"description": "Parameters for get_stress",
"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"
}
},
"required": [
"start_date",
"end_date"
],
"title": "GetStressParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"StressDay": {
"description": "One day of stress + recovery summary.",
"properties": {
"day": {
"title": "Day",
"type": "string"
},
"stress_high_min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Minutes spent in high stress",
"title": "Stress High Min"
},
"recovery_high_min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Minutes spent in high recovery",
"title": "Recovery High Min"
},
"day_summary": {
"anyOf": [
{
"enum": [
"restored",
"normal",
"stressful"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Daily stress/recovery summary",
"title": "Day Summary"
}
},
"required": [
"day"
],
"title": "StressDay",
"type": "object"
}
},
"description": "Result from get_stress",
"properties": {
"days": {
"items": {
"$ref": "#/$defs/StressDay"
},
"title": "Days",
"type": "array"
},
"missing_dates": {
"items": {
"type": "string"
},
"title": "Missing Dates",
"type": "array"
}
},
"required": [
"days",
"missing_dates"
],
"title": "GetStressResult",
"type": "object"
} # get_trends read
Track how an Oura metric (sleep duration, readiness, HRV, RHR, steps, SpO2, temperature) has trended over time — week-over-week / month-over-month change with rolling mean, stdev, min/max.
Full description
Compute rolling window statistics and percent change for one metric.
This analyzes trends in Oura data by calculating mean, standard deviation,
and comparing against a prior period.
Parameters:
metric (str, required): Metric to analyze. Valid values:
- "sleep_duration": Total sleep hours
- "sleep_efficiency": Sleep efficiency percentage
- "readiness_score": Daily readiness score
- "activity_score": Daily activity score
- "steps": Daily step count
- "resting_hr": Resting heart rate (from readiness)
- "hrv": HRV balance (from readiness)
- "spo2": Blood oxygen saturation
- "temperature_deviation": Body temperature deviation
window_days (int, optional): Window size in days (min 7). Default: 28
end_date (str, required): End date in YYYY-MM-DD format
compare_to (str, optional): Comparison period. Valid values:
- "prior_window": Previous window of same length
- "prior_week": 7 days before
- "prior_month": 30 days before
Default: "prior_window"
Returns:
GetTrendsResult with:
- mean: Average value in the window
- std_dev: Standard deviation
- min_value: Minimum value
- max_value: Maximum value
- change_pct: Percent change vs comparison period
- comparison_mean: Mean of comparison period
Errors:
UNAUTHORIZED: Could not authenticate
VALIDATION_ERROR: Invalid metric or date
DATA_GAP: Insufficient data for analysis | Parameter | Type | Required | Description |
|---|---|---|---|
metric | "sleep_duration" | "sleep_efficiency" | "readiness_score" | "activity_score" | "steps" | "resting_hr" | "hrv" | "spo2" | "temperature_deviation" | Yes | Metric to analyze for trends |
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" |
Parameter schema (JSON)
{
"description": "Parameters for get_trends",
"properties": {
"metric": {
"description": "Metric to analyze for trends",
"enum": [
"sleep_duration",
"sleep_efficiency",
"readiness_score",
"activity_score",
"steps",
"resting_hr",
"hrv",
"spo2",
"temperature_deviation"
],
"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"
}
},
"required": [
"metric",
"end_date"
],
"title": "GetTrendsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"description": "Result from get_trends",
"properties": {
"metric": {
"description": "Metric analyzed",
"title": "Metric",
"type": "string"
},
"window_days": {
"description": "Window size used",
"title": "Window Days",
"type": "integer"
},
"end_date": {
"description": "End date of analysis",
"title": "End Date",
"type": "string"
},
"mean": {
"description": "Mean value in the window",
"title": "Mean",
"type": "number"
},
"std_dev": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Standard deviation",
"title": "Std Dev"
},
"min_value": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum value in window",
"title": "Min Value"
},
"max_value": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum value in window",
"title": "Max Value"
},
"change_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Percent change vs comparison period",
"title": "Change Pct"
},
"comparison_mean": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Mean of comparison period",
"title": "Comparison Mean"
}
},
"required": [
"metric",
"window_days",
"end_date",
"mean"
],
"title": "GetTrendsResult",
"type": "object"
} # get_user_config read
Return the Oura user's ring configuration and optional personal profile.
Full description
Return the user's ring configuration and optional personal profile.
Use this to verify ring setup and retrieve user profile information.
Parameters:
include_profile (bool, optional): Whether to include personal profile info.
Default: false. Requires 'personal' scope to be granted.
Returns:
GetUserConfigResult with:
- ring_config: Primary ring configuration (model, firmware, size, etc.)
- personal_info: Personal profile if requested and available
Errors:
UNAUTHORIZED: User has not connected Oura or token is invalid/expired
INSUFFICIENT_SCOPE: Requested profile but 'personal' scope not granted | Parameter | Type | Required | Description |
|---|---|---|---|
include_profile | boolean | No | Whether to include personal profile info (requires 'personal' scope) Default: false |
Parameter schema (JSON)
{
"description": "Parameters for get_user_config",
"properties": {
"include_profile": {
"default": false,
"description": "Whether to include personal profile info (requires 'personal' scope)",
"title": "Include Profile",
"type": "boolean"
}
},
"title": "GetUserConfigParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"PersonalInfo": {
"description": "User's personal profile information",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Unique user identifier",
"title": "Id"
},
"age": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "User's age in years",
"title": "Age"
},
"weight": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "User's weight in kg",
"title": "Weight"
},
"height": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "User's height in meters",
"title": "Height"
},
"biological_sex": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "User's biological sex",
"title": "Biological Sex"
},
"email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "User's email address",
"title": "Email"
}
},
"title": "PersonalInfo",
"type": "object"
},
"RingConfiguration": {
"description": "Configuration details for a single Oura ring",
"properties": {
"id": {
"description": "Unique identifier for the ring configuration",
"title": "Id",
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Color of the ring (e.g., 'silver', 'black', 'gold', 'stealth')",
"title": "Color"
},
"design": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Design variant of the ring (e.g., 'heritage', 'horizon')",
"title": "Design"
},
"firmware_version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Current firmware version installed on the ring",
"title": "Firmware Version"
},
"hardware_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Hardware generation/type of the ring",
"title": "Hardware Type"
},
"set_up_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO8601 timestamp when the ring was set up",
"title": "Set Up At"
},
"size": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Ring size (US sizing)",
"title": "Size"
}
},
"required": [
"id"
],
"title": "RingConfiguration",
"type": "object"
}
},
"description": "Result from get_user_config",
"properties": {
"ring_config": {
"anyOf": [
{
"$ref": "#/$defs/RingConfiguration"
},
{
"type": "null"
}
],
"default": null,
"description": "Primary ring configuration if available"
},
"personal_info": {
"anyOf": [
{
"$ref": "#/$defs/PersonalInfo"
},
{
"type": "null"
}
],
"default": null,
"description": "Personal profile info if requested and available"
}
},
"title": "GetUserConfigResult",
"type": "object"
} # get_vo2_max read
Fetch Oura VO2 max readings (estimated cardiorespiratory fitness) for a date range — Oura-unique signal with no Fitbit equivalent.
Full description
VO2 max readings over a date range.
Returns Oura's estimated VO2 max (ml/kg/min) per reading. Oura updates this
value roughly weekly based on heart-rate-during-activity inputs, so daily
rows are expected to be sparse rather than dense. This is an Oura-unique
signal with no Fitbit equivalent.
Parameters:
start_date (str, required): Inclusive start date (YYYY-MM-DD).
end_date (str, required): Inclusive end date (YYYY-MM-DD).
Returns:
GetVo2MaxResult with `days`, `missing_dates` (most days will be 'missing'
even with active wear, as this signal is intrinsically slow-cadence).
Errors:
UNAUTHORIZED: Could not authenticate.
VALIDATION_ERROR: Invalid date format or start_date > end_date. | Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Inclusive start date (YYYY-MM-DD) |
end_date | string | Yes | Inclusive end date (YYYY-MM-DD) |
Parameter schema (JSON)
{
"description": "Parameters for get_vo2_max",
"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"
}
},
"required": [
"start_date",
"end_date"
],
"title": "GetVo2MaxParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"Vo2MaxDay": {
"description": "One reading of VO2 max data (cadence is roughly weekly).",
"properties": {
"day": {
"title": "Day",
"type": "string"
},
"vo2_max": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Estimated VO2 max (ml/kg/min)",
"title": "Vo2 Max"
},
"timestamp": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO timestamp of measurement",
"title": "Timestamp"
}
},
"required": [
"day"
],
"title": "Vo2MaxDay",
"type": "object"
}
},
"description": "Result from get_vo2_max",
"properties": {
"days": {
"items": {
"$ref": "#/$defs/Vo2MaxDay"
},
"title": "Days",
"type": "array"
},
"missing_dates": {
"items": {
"type": "string"
},
"title": "Missing Dates",
"type": "array"
}
},
"required": [
"days",
"missing_dates"
],
"title": "GetVo2MaxResult",
"type": "object"
} # get_workout_sessions read
Fetch individual Oura workout sessions with activity type, duration, calories, heart rate, and distance.
Full description
Get workout session data for a date range.
Retrieves individual workout records from the Oura Ring, including
activity type, duration, calories, heart rate, and distance.
Parameters:
start_date (str, required): Inclusive start date (YYYY-MM-DD)
end_date (str, required): Inclusive end date (YYYY-MM-DD)
Returns:
GetWorkoutSessionsResult with:
- sessions: Array of workout session objects with:
- id, date, activity type
- start_time, end_time, duration_minutes
- calories, distance_meters
- average_heart_rate, max_heart_rate
- intensity, source
- summary: Statistics (total_sessions, total_calories, total_distance, avg_duration)
Errors:
UNAUTHORIZED: Could not authenticate
VALIDATION_ERROR: Invalid date format or start_date > end_date
DATA_GAP: No workout data for the specified 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) |
Parameter schema (JSON)
{
"description": "Parameters for get_workout_sessions",
"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"
}
},
"required": [
"start_date",
"end_date"
],
"title": "GetWorkoutSessionsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"WorkoutSession": {
"description": "Individual workout session",
"properties": {
"id": {
"description": "Workout session ID",
"title": "Id",
"type": "string"
},
"date": {
"description": "Day (YYYY-MM-DD)",
"title": "Date",
"type": "string"
},
"activity": {
"description": "Activity type (e.g. walking, running, cycling)",
"title": "Activity",
"type": "string"
},
"start_time": {
"description": "ISO8601 start datetime",
"title": "Start Time",
"type": "string"
},
"end_time": {
"description": "ISO8601 end datetime",
"title": "End Time",
"type": "string"
},
"duration_minutes": {
"description": "Duration in minutes",
"title": "Duration Minutes",
"type": "integer"
},
"calories": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Calories burned",
"title": "Calories"
},
"distance_meters": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Distance in meters",
"title": "Distance Meters"
},
"average_heart_rate": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Average heart rate (bpm)",
"title": "Average Heart Rate"
},
"max_heart_rate": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Max heart rate (bpm)",
"title": "Max Heart Rate"
},
"intensity": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Intensity level",
"title": "Intensity"
},
"source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Data source (manual, auto_detected)",
"title": "Source"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "User-defined label for the workout",
"title": "Label"
}
},
"required": [
"id",
"date",
"activity",
"start_time",
"end_time",
"duration_minutes"
],
"title": "WorkoutSession",
"type": "object"
},
"WorkoutSessionsSummary": {
"description": "Summary statistics for workout sessions",
"properties": {
"total_sessions": {
"description": "Number of workout sessions",
"title": "Total Sessions",
"type": "integer"
},
"total_calories": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Total calories burned",
"title": "Total Calories"
},
"total_distance_meters": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Total distance in meters",
"title": "Total Distance Meters"
},
"avg_duration_minutes": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Average duration in minutes",
"title": "Avg Duration Minutes"
}
},
"required": [
"total_sessions"
],
"title": "WorkoutSessionsSummary",
"type": "object"
}
},
"description": "Result from get_workout_sessions",
"properties": {
"sessions": {
"description": "Workout sessions for the date range",
"items": {
"$ref": "#/$defs/WorkoutSession"
},
"title": "Sessions",
"type": "array"
},
"summary": {
"$ref": "#/$defs/WorkoutSessionsSummary",
"description": "Summary statistics"
}
},
"required": [
"sessions",
"summary"
],
"title": "GetWorkoutSessionsResult",
"type": "object"
}