| 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
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.