Oura Trends Puller

Playwright automation for exporting Oura Cloud Trends data as CSV files.

This project logs in through the normal Oura Cloud browser flow, saves a local browser session, and exports Trends metrics into local CSV files. It is intended for people who want a reproducible local backup or analysis-friendly CSV snapshots of their own Oura data.

What It Does

• Authenticates to https://cloud.ouraring.com using your Oura email-code login flow.
• Saves browser auth state locally under .auth/.
• Exports the currently selected Oura Trends range, or an explicit historical range.
• Exports either the standard browser CSV download or one CSV per Trends metric.
• Supports manual one-time-code entry.
• Optionally integrates with your own OTP helper command or script.

What It Does Not Do

• It does not include Oura credentials, email-provider credentials, OAuth tokens, or personal account identifiers.
• It does not include raw health data.
• It does not call a personal endpoint.
• It does not provide medical advice or health interpretation.
• It is not an official Oura product.

Use it only with accounts and data you are authorized to access, and comply with the terms that apply to your Oura account.

Requirements

• Node.js 18 or newer.
• An Oura account with access to Oura Cloud Trends.
• Chromium installed through Playwright.

npm install
npm run playwright:install

Quick Start

Create a local .env:

cp .env.example .env

Set your Oura email:

OURA_EMAIL=you@example.com
OURA_HEADLESS=false

Run the live auth flow:

npm run oura:auth-live

When the script prints WAITING_FOR_OTP_FILE, enter the Oura email code in the terminal, or write the six-digit code to:

.auth/oura-otp.txt

Then export all Trends metrics:

npm run oura:export-all

CSV files are written to:

exports/oura/

Explicit Historical Exports

By default, oura:export-all uses the date range currently selected in Oura Cloud.

For reproducible historical exports, pass both dates:

npm run oura:export-all -- --start-date 2024-01-01 --end-date 2024-12-31

Or set them in .env:

OURA_TRENDS_START_DATE=2024-01-01
OURA_TRENDS_END_DATE=2024-12-31

When an explicit range is used, output filenames include the range:

2026-07-04_oura_trend_2024-01-01_to_2024-12-31_average-hrv.csv

Commands

npm run oura:auth
npm run oura:auth-live
npm run oura:auth-assisted
npm run oura:export
npm run oura:export-all
npm run oura:daily:auto
npm run oura:list-trend-metrics
npm run oura:inspect-trends

oura:export uses the browser download flow. oura:export-all enumerates the Trends export modal and requests one CSV per metric from the Oura Cloud Trends CSV endpoint using your authenticated browser session.

Automated OTP Retrieval

Manual OTP entry is the default safe path. Automated OTP retrieval is optional and integration-neutral.

To use it, provide an OTP helper command:

OURA_OTP_COMMAND="your-otp-helper --write-code-to-file"
npm run oura:daily:auto -- --retries 2

The command receives these environment variables:

OURA_OTP_FILE
OURA_OTP_QUERY
OURA_OTP_MAX_RESULTS

It can write the six-digit Oura code to OURA_OTP_FILE or print the code to stdout.

You can also use a Python helper script:

OURA_OTP_FETCH_SCRIPT=./local/fetch_oura_otp.py
npm run oura:daily:auto -- --retries 2

The Python helper script must accept:

--write-code-to-file
--otp-file <path>
--query <email-search-query>
--max-results <count>
--quiet-code

It should write only the six-digit Oura code to the --otp-file path.

No email-provider or OAuth implementation is bundled.

Local Files And Privacy

The following paths are intentionally ignored by Git:

• .env
• .auth/
• exports/
• node_modules/
• Playwright test/report folders

Do not publish:

• browser session state
• one-time codes
• OAuth client secrets
• OAuth token files
• raw CSV exports if they contain personal health data
• diagnostic screenshots or HTML from authenticated pages

Output

Typical output files:

exports/oura/2026-07-04_oura_trend_sleep-score.csv
exports/oura/2026-07-04_oura_trend_average-hrv.csv
exports/oura/2026-07-04_oura_trend_steps.csv

CSV durations may be exported as seconds, depending on the metric.

Troubleshooting

If the saved session expires:

npm run oura:auth-live

If selectors or export controls change:

npm run oura:inspect-trends
npm run oura:list-trend-metrics

If explicit range export fails immediately, check that both dates are set and use YYYY-MM-DD.

Public Release Checklist

Before publishing a fork or copy:

• Confirm .env, .auth/, and exports/ are absent.
• Run a text scan for personal emails, local usernames, credential paths, and token values.
• Keep examples generic, such as you@example.com.
• Keep the license file with the published copy.

License

AGPL-3.0-only.