vellum-ai 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-setupskill) - Credential stored:
oura/access_tokenwith injection template forapi.ouraring.com(Authorization header, Bearer prefix) - Credential ID can be found via
assistant credentials list --search oura(filter for fieldaccess_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_dateandend_dateinYYYY-MM-DDformat - Heart rate: Uses
start_datetimeandend_datetimein 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-setupskill'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.