oura

name	oura
description	Pull sleep, activity, readiness, heart rate, and other health data from a connected Oura Ring via the Oura Cloud API V2
compatibility	Designed for Vellum personal assistants
metadata	{"emoji":"💍","vellum":{"category":"health","display-name":"Oura Ring","includes":["oura-setup"]}}

Oura Ring — Data Access

Pull sleep, activity, readiness, heart rate, and other health data from a connected Oura Ring via the Oura Cloud API V2.

For initial setup (OAuth, app registration, token exchange), see the oura-setup skill.

Prerequisites

• Oura Ring already connected via OAuth (see oura-setup skill)
• Credential stored: oura / access_token with injection template for api.ouraring.com (Authorization header, Bearer prefix)
• Credential ID can be found via assistant credentials list --search oura (filter for field access_token)

Making Requests

All requests go through the credential proxy — no need to manually attach tokens.

curl -s "https://api.ouraring.com/v2/usercollection/{endpoint}?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD"

Run via bash with:

• network_mode: "proxied"
• credential_ids: ["<oura access_token credential_id>"]

Endpoints

Endpoint	What It Returns	Best For
personal_info	Age, weight, height, email	Connection test
daily_sleep	Sleep score, duration, efficiency, stages	Morning check-in
sleep	Detailed sleep periods — HR, HRV, movement, timestamps	Deep sleep analysis
daily_readiness	Readiness score, HRV balance, recovery index	Morning readiness
daily_activity	Steps, calories, movement, MET data, activity score	Daily activity summary
heartrate	Continuous HR readings (uses start_datetime/end_datetime ISO format)	Workout HR, resting HR
workout	Detected workouts — HR, calories, duration, type	Exercise tracking
daily_spo2	Blood oxygen (SpO2) nightly average	Breathing/oxygen
daily_stress	Stress score, recovery periods	Stress monitoring
ring_configuration	Ring model, firmware, color, design	Ring info

Query Parameters

• Most endpoints: start_date and end_date in YYYY-MM-DD format
• Heart rate: Uses start_datetime and end_datetime in ISO 8601 format (e.g. 2025-01-15T00:00:00-05:00)
• Personal info / ring config: No date params needed
• Omitting dates usually returns recent data (last 1-7 days depending on endpoint)

Common Patterns

Morning health check

Pull sleep + readiness + activity for today:

DATE=$(date +%Y-%m-%d)
curl -s "https://api.ouraring.com/v2/usercollection/daily_sleep?start_date=$DATE&end_date=$DATE"
curl -s "https://api.ouraring.com/v2/usercollection/daily_readiness?start_date=$DATE&end_date=$DATE"

Workout details with HR

YESTERDAY=$(date -v-1d +%Y-%m-%d)
TODAY=$(date +%Y-%m-%d)
curl -s "https://api.ouraring.com/v2/usercollection/workout?start_date=$YESTERDAY&end_date=$TODAY"

Heart rate during a specific window

# Adjust the datetime range as needed (ISO 8601 with timezone offset)
curl -s "https://api.ouraring.com/v2/usercollection/heartrate?start_datetime=YYYY-MM-DDT23:00:00-05:00&end_datetime=YYYY-MM-DDT01:00:00-05:00"

Notes

• New rings need 1-2 nights to calibrate before sleep/readiness scores are meaningful
• Sleep data appears a few hours after waking
• Short workouts (<15 min) may not be auto-detected — check raw heart rate instead
• Heart rate endpoint can return large datasets — keep time windows tight
• Rate limit: 5,000 requests per 5 minutes
• Tokens expire after ~30 days. Refresh using the oura-setup skill's token refresh instructions.

Token Refresh

When the access token expires, use the refresh token via the oura-setup skill:

curl -s -X POST "https://api.ouraring.com/oauth/token" \
  -d "grant_type=refresh_token&refresh_token=REFRESH_TOKEN&client_id=CLIENT_ID&client_secret=CLIENT_SECRET"

Store the new access_token and refresh_token. See oura-setup for full details.