REST API v1

The VitalTrends API lets you query your own health data programmatically. Build scripts, notebooks, automations, or pipe your data into any tool you like.

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Keep your API key secret. Regenerate it from the Developer settings page if it is ever exposed.

Base URL

https://vitaltrends.net/api/v1

All public REST endpoints are versioned by URL path. The current stable version is v1.

All endpoints return JSON. Dates are ISO 8601 strings (YYYY-MM-DD). Timestamps are UTC unless a field is explicitly documented as a local date.

Versioning

v1 changelog

Endpoints

Workouts

curl -s "https://vitaltrends.net/api/v1/workouts/hevy?start=2026-05-01&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq .

Muscle group usage

GET /training/muscle-groups/usage summarizes your canonical Training Log across Hevy, API uploads, and imports. amount is lifted training volume in kilograms, calculated as weight_kg × reps; percentage is that group's share of the returned total_amount, and workout_count counts distinct sessions containing the group.

Provide either both start_date and end_date as inclusive local calendar dates, or all_time=true. Date ranges use your profile timezone. Unclassified exercises appear as Other, and a range with no data returns total_amount: 0 with an empty muscle_groups array.

curl -s "https://vitaltrends.net/api/v1/training/muscle-groups/usage?start_date=2026-06-01&end_date=2026-06-30" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq .

{
  "range": {
    "start_date": "2026-06-01",
    "end_date": "2026-06-30",
    "all_time": false
  },
  "metric": "volume_kg",
  "total_amount": 1234.0,
  "muscle_groups": [
    {
      "muscle_group": "Back",
      "amount": 740.4,
      "workout_count": 8,
      "percentage": 60.0
    }
  ]
}

For full history, call:

curl -s "https://vitaltrends.net/api/v1/training/muscle-groups/usage?all_time=true" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq .

Uploading workouts (write API)

Push completed strength workouts into VitalTrends from an agent, script, or another app. Anything you upload appears in your Training Log, in your stats and muscle map, and in the unified workout feed, deduplicated against Hevy and everything else.

Quick start: one push, one session

The simplest path is /workout-logs/import with format: "agent-rows-v1": send one row per exercise and the whole request becomes one session. Set columns (set_1, set_2, …) are read in order, so any number of sets works. The optional muscle_group classifies the exercise, the source column is treated as a per-exercise image path, and notes is preserved verbatim.

Send the real workout start time whenever you want uploaded sets to join a matching WHOOP, Apple Health, or other device session. Also send duration_seconds when you know it. A precise start without a duration can still join a strongly overlapping strength session, but a date-only upload uses noon in the profile timezone and is intentionally not attached by a loose same-day guess.

curl -s -X POST "https://vitaltrends.net/api/v1/workout-logs/import" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6d1f0e60-6f2a-4a1e-9d1a-2f3b4c5d6e7f" \
  -d '{
    "format": "agent-rows-v1",
    "title": "Pull day",
    "date": "2026-07-06",
    "time": "18:08 WEST",
    "end_time": "19:00 WEST",
    "timezone": "Europe/Lisbon",
    "rows": [
      {
        "date": "2026-07-06", "time_lisbon": "18:08 WEST",
        "exercise": "Lat pulldown",
        "equipment": "Hoist Fitness ROC-IT Lat Pulldown",
        "muscle_group": "back",
        "set_1": "12x52kg", "set_2": "12x52kg", "set_3": "12x61kg",
        "total_volume_kg": "1980",
        "source": "attachments/2026-07-06-lat-pulldown.jpg",
        "notes": "User-provided weights treated as kg."
      },
      {
        "date": "2026-07-06", "time_lisbon": "18:44 WEST",
        "exercise": "Overhead press",
        "equipment": "Cybex Eagle Overhead Press",
        "set_1": "12x31", "set_2": "12x40", "set_3": "12x49",
        "total_volume_kg": "1440",
        "notes": "User omitted kg, treated as kg by context."
      }
    ]
  }' | jq .

Top-level timing is optional. Without it, the earliest valid row time remains the session start. Top-level started_at has highest priority, followed by date plus time, date plus time_lisbon, and then the earliest row. End time is never inferred from exercise rows.

The response is the created session (status 201) with server-derived exercise_key / equipment_key, recomputed total_volume_kg, normalized session timing, and an import summary plus any warnings (for example when a unit was inferred). A CSV body works too: send Content-Type: text/csv with the raw rows and the same ?format=agent-rows-v1.

Import a MacroFactor export

The Training Log import control accepts the original .xlsx workbook downloaded from MacroFactor, plus MacroFactor CSV exports. One file can contain many workouts. To upload through the API, send multipart form data with a maximum file size of 10 MB:

curl -s -X POST "https://vitaltrends.net/api/v1/workout-logs/import" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "format=macrofactor-xlsx-v1" \
  -F "[email protected]" | jq .

Use macrofactor-csv-v1 for a .csv file. Raw CSV is also accepted as the request body with Content-Type: text/csv and ?format=macrofactor-csv-v1.

VitalTrends groups rows by workout date and name, converts the workbook's Excel dates, converts pounds to kilograms for canonical storage, and preserves warm-up/standard set type, reps, RIR-derived RPE, duration, and distance. A repeated import uses deterministic session identities, so it does not create duplicate workouts.

MacroFactor exports do not include a muscle-group column. VitalTrends classifies standard MacroFactor exercise names into the canonical muscle groups below. An unfamiliar exercise remains visible and enters the Training Log review queue instead of receiving a guessed classification.

MacroFactor does not include the workout start time in this export format. Imported sessions therefore use 12:00 in the profile timezone. They remain complete Training Log sessions, but they are not loosely joined to a device workout using date alone.

Canonical structured JSON

For full control, POST /workout-logs with a structured body. Each set is either a "{reps}x{weight}{unit?}" string or an object {"reps": 12, "weight": {"value": 52, "unit": "kg"}}.

curl -s -X POST "https://vitaltrends.net/api/v1/workout-logs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "hermes-2026-07-06-pull",
    "title": "Pull day",
    "date": "2026-07-06", "time": "18:08 WEST", "end_time": "19:00 WEST",
    "timezone": "Europe/Lisbon",
    "default_unit": "kg", "dedup_mode": "merge",
    "exercises": [
      {
        "name": "Lat pulldown",
        "equipment": "Hoist Fitness ROC-IT Lat Pulldown (RS-2201 visible)",
        "muscle_group": "back",
        "sets": ["12x52kg", "12x52kg", "12x61kg"],
        "media": [{"external_ref": "attachments/2026-07-06-lat-pulldown.jpg"}]
      }
    ]
  }' | jq .

Muscle groups

Add the optional muscle_group field to each structured exercise or each agent-rows-v1 row. CSV imports can use a muscle_group column. The value classifies the canonical exercise definition used by Training Log volume analytics and the muscle map.

Use one of these canonical lower-case values:

Values are case-insensitive, and spaces or hyphens are normalized like underscores. A supplied value fills a definition that does not already have a muscle classification. Existing classifications, including Hevy catalog data and a user's manual correction, are not overwritten by later uploads. If muscle_group is omitted, VitalTrends uses an existing exercise definition when available; otherwise the exercise remains in Other and is added to the Needs muscle group review queue in Training Log.

Selecting a muscle group in the Training Log review queue, exercise editor, or workout detail page creates a user-specific reusable mapping. The normalized exercise name will resolve automatically on future uploads, while historical muscle maps, percentages, and GET /training/muscle-groups/usage results use the correction immediately. Workout-log detail responses expose the resolved title-case value as exercises[].muscle_group, or null while it remains unmatched.

Sets, units, and time

• Set grammar {reps}x{weight}{unit?}: 12x52kg, 12x115lb (converted to kg), or 12x52 (unit missing, inferred as kg and flagged with a warning). Bodyweight sets can be just 12.
• Weights are normalized to kilograms; the raw value and unit you sent are preserved, and unit_inferred records whether the unit was assumed.
• Time: send an ISO started_at with a timezone, or a date plus a local time with a zone abbreviation like 18:08 WEST. To store workout duration, also send ISO ended_at, local end_time, or integer duration_seconds. An end time computes duration; duration computes the end. If both are sent, they must agree within one second.
• Overnight sessions: a local end_time at or before the start clock time is treated as the next local day. Durations must be from 1 second through 24 hours.
• Response timing: responses include UTC started_at and ended_at, duration_seconds, the IANA timezone, local local_time and local_end_time, and duration_minutes. Workouts without an end remain valid and return null end/duration fields.
• total_volume_kg is always recomputed server-side from the sets; a value you send is cross-checked and, if it disagrees, surfaced as a warning rather than trusted.

Use ISO timestamps when the agent already knows the exact instants:

{
  "started_at": "2026-07-15T16:55:00Z",
  "ended_at": "2026-07-15T17:35:00Z",
  "timezone": "Europe/Lisbon"
}

Or send a duration and let VitalTrends derive the end:

{
  "date": "2026-07-15",
  "time": "17:55 WEST",
  "timezone": "Europe/Lisbon",
  "duration_seconds": 2400
}

Idempotency

Send an Idempotency-Key: <uuid> header on any create. The same key with the same payload and behavior options replays the stored response (safe retries); changing rows, timing, dedup_mode, or allow_partial with the same key returns 409 idempotency_conflict. Keys are remembered for 7 days.

Deduplication

Uploads dedupe so the same physical session arriving from Hevy and from your agent collapse into one. Agent sets also appear inside a matching unified device workout when activity and time overlap strongly; links from either source open the complete grouped session. Control write-time dedup per request with dedup_mode:

An invalid mode returns 422. Preview always returns outcome: "preview"; candidate is present when an existing session would be merged or updated, and session contains the fully normalized timing that would be used:

{
  "outcome": "preview",
  "would": "update",
  "candidate": {
    "id": "019f7b0b-7083-708e-b180-21c1f5041704",
    "source": "agent"
  },
  "warnings": [],
  "session": {
    "started_at": "2026-07-15T16:55:00+00:00",
    "ended_at": "2026-07-15T17:35:00+00:00",
    "timezone": "Europe/Lisbon",
    "time_provenance": "explicit_iana",
    "local_time": "2026-07-15 17:55",
    "local_end_time": "2026-07-15 18:35",
    "duration_seconds": 2400,
    "duration_minutes": 40
  }
}

Reading, editing, and media

GET /workout-logs lists your sessions and GET /workout-logs/{id} returns one with its exercises, sets, and media. Edit scalar fields with PATCH /workout-logs/{id}, replace the whole exercise tree with PUT /workout-logs/{id}/exercises, and remove a session with DELETE /workout-logs/{id}.

curl -s -X PATCH "https://vitaltrends.net/api/v1/workout-logs/WORKOUT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Shoulders and triceps",
    "date": "2026-07-15",
    "time": "17:55 WEST",
    "end_time": "18:35 WEST",
    "timezone": "Europe/Lisbon"
  }' | jq .

PATCH keeps timing consistent. Updating only duration_seconds moves the end. Updating only an end recomputes duration. Updating only the start preserves an existing duration and moves the end. Set ended_at, end_time, or duration_seconds to null to clear a known end; an explicit non-null end still wins when duration is null.

{ "duration_seconds": 2700 }

The example above preserves the current start and sets the end 45 minutes later. To return a workout to unknown/open-ended timing, send any one of these explicit clears:

{ "ended_at": null }

{ "end_time": null }

{ "duration_seconds": null }

Sessions synced from Hevy are read-only and return 409 source_managed on any edit. To attach a photo, POST /workout-media (multipart image), then reference the returned media_id in an exercise's media array.

Errors

Timing validation uses 422 validation_failed with a specific message:

WHOOP

Oura

Withings

Withings list endpoints accept the shared pagination and date filters: start, end, page, and per_page. Measurement filters apply to measured_at. Sleep filters apply to start_at.

Withings measurement fields

Withings Sleep Analyzer fields

curl -s "https://vitaltrends.net/api/v1/withings/sleeps?start=2026-06-01&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq .

Apple Health

Daily summary, one request for a full picture

Use this when you want the morning-dashboard shape: every metric for a given date, including wrist temperature, a sleep stage breakdown (deep, rem, core, awake, in_bed) and full workout metadata (sport, duration, HR min/avg/max, energy, flights climbed).

curl -s "https://vitaltrends.net/api/v1/apple-health/daily-summary?date=2026-04-21" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq .

{
  "data": {
    "date": "2026-04-21",
    "activity": {
      "steps": 12500,
      "distance_km": 8.234,
      "active_energy_kcal": 487.2,
      "basal_energy_kcal": 1789.4,
      "apple_move_time_min": 45,
      "apple_exercise_time_min": 28,
      "apple_stand_time_min": 180,
      "flights_climbed": 12,
      "time_in_daylight_min": 87,
      "apple_stand_hours": 12
    },
    "heart": {
      "avg_heart_rate": 68,
      "min_heart_rate": 52,
      "max_heart_rate": 134,
      "resting_heart_rate": 56,
      "hrv_ms": 45.2,
      "respiratory_rate": 14.2,
      "spo2_pct": 97.8,
      "vo2_max": 42.5,
      "wrist_temperature_c": 36.42,
      "wrist_temperature_min_c": 36.10,
      "wrist_temperature_max_c": 36.70
    },
    "sleep": {
      "total_minutes": 452,
      "start_time": "2026-04-20T23:14:00+00:00",
      "end_time": "2026-04-21T06:46:00+00:00",
      "stages": {
        "deep_min": 68,
        "rem_min": 92,
        "core_min": 256,
        "light_min": 0,
        "awake_min": 36,
        "in_bed_min": 480,
        "unknown_min": 0
      },
      "sources": ["Apple Watch"]
    },
    "body": {
      "weight_kg": 75.20,
      "body_fat_pct": 18.40,
      "lean_body_mass_kg": 61.30,
      "bmi": 23.4,
      "height_m": 1.79,
      "body_comp_date": "2026-04-18"
    },
    "workouts": [
      {
        "uuid": "018f0a3b-1c7e-7d9a-8a2b-8c5c47b3d401",
        "type": "Functional Strength Training",
        "sport_key": "functional_strength_training",
        "start_time": "2026-04-21T07:02:00+00:00",
        "end_time": "2026-04-21T07:47:00+00:00",
        "duration_min": 45,
        "active_energy_kcal": 320,
        "distance_m": null,
        "avg_heart_rate": 132,
        "min_heart_rate": 85,
        "max_heart_rate": 165,
        "flights_climbed": 3,
        "elevation_gain_m": null,
        "source": "Apple Watch"
      }
    ]
  }
}

/apple-health/daily-summary and /apple-health/daily expose wrist temperature as wrist_temperature_c, wrist_temperature_min_c, and wrist_temperature_max_c. The average uses sample_count weighting when multiple processed rows exist for the same day.

Per-type time series, with optional metadata

Use this when you want processed per-type rows, a date range, or per-segment sleep stages. Use type=sleeping_wrist_temp for Apple Health wrist temperature rows. Pass include=metadata to reveal the metadata field (sleep stage, workout type, labels). For individual CGM glucose readings, use /glucose/readings.

/apple-health?type=<type> responses are cached for 5 minutes per user and exact query string. Responses include Cache-Control: private, max-age=300, so clients should avoid rapid repeat polling and reuse identical responses during that window.

curl -s "https://vitaltrends.net/api/v1/apple-health?type=sleep&start=2026-04-20&end=2026-04-21&include=metadata" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq .

{
  "data": [
    {
      "data_type": "sleep",
      "date": "2026-04-20",
      "start_time": "2026-04-21T01:45:00+00:00",
      "end_time": "2026-04-21T05:45:00+00:00",
      "value": 0,
      "value_min": null,
      "value_max": null,
      "sample_count": 1,
      "unit": "hr",
      "source": "Apple Watch",
      "metadata": { "stage": "core" }
    },
    {
      "data_type": "sleep",
      "date": "2026-04-20",
      "start_time": "2026-04-20T23:15:00+00:00",
      "end_time": "2026-04-21T00:15:00+00:00",
      "value": 0,
      "value_min": null,
      "value_max": null,
      "sample_count": 1,
      "unit": "hr",
      "source": "Apple Watch",
      "metadata": { "stage": "deep" }
    }
  ],
  "links": { "first": "...", "last": null, "prev": null, "next": null },
  "meta": { "current_page": 1, "from": 1, "path": "...", "per_page": 50, "to": 2 }
}

Valid type values

Availability depends on which HealthKit sensors and iOS version your device supports. Types that are defined but not yet ingested by the VitalTrends iOS companion app are listed in meta.unavailable_types on the daily summary response.

Glucose / CGM

Glucose data is available when a CGM or glucose app writes blood_glucose samples into Apple Health and the VitalTrends iOS companion app syncs them.

Glucose analytics

Use this when you want the same glucose analysis that powers the web dashboard.

curl -s "https://vitaltrends.net/api/v1/glucose?days=30" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq .

{
  "data": {
    "config": {
      "targetLow": 70,
      "targetHigh": 140,
      "clinicalHigh": 180,
      "unit": "mg/dL"
    },
    "stats": {
      "average_glucose": { "value": 112.4, "source": "daily_weighted", "sample_count": 8064 },
      "gmi": { "value": 6.0, "available": true, "reason": null, "days_with_data": 28 },
      "time_in_range": { "source": "raw", "range_70_140_pct": 82.1, "range_70_180_pct": 96.5, "total": 8064 },
      "variability": { "value": 18.9, "source": "raw_cv", "proxy_value": null, "stable_threshold": 36 },
      "min_max": { "min": 64.0, "max": 184.0 }
    },
    "daily": [
      {
        "date": "2026-05-31",
        "value": 111.8,
        "value_min": 82.0,
        "value_max": 154.0,
        "sample_count": 288,
        "unit": "mg/dL"
      }
    ],
    "time_in_range": {
      "source": "raw",
      "bands": []
    },
    "agp": {
      "available": true,
      "bucket_minutes": 30,
      "points": []
    },
    "correlations": {
      "available": true,
      "day_explorer": {}
    },
    "empty": false,
    "has_any_data": true
  }
}

When no glucose data exists, /glucose returns empty: true and has_any_data: false instead of an error.

Raw glucose readings

Use this when you need individual CGM readings rather than daily aggregates.

curl -s "https://vitaltrends.net/api/v1/glucose/readings?start=2026-05-01&end=2026-05-07&per_page=200" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq .

{
  "data": [
    {
      "sample_id": 214242011,
      "data_type": "blood_glucose",
      "recorded_at": "2026-05-07T23:36:13+00:00",
      "start_time": "2026-05-07T23:36:13+00:00",
      "end_time": "2026-05-07T23:36:13+00:00",
      "value": 99.1,
      "unit": "mg/dL",
      "source": "CGM"
    }
  ],
  "links": { "first": "...", "last": null, "prev": null, "next": null },
  "meta": { "current_page": 1, "from": 1, "path": "...", "per_page": 200, "to": 1 }
}

/glucose/readings supports the common list parameters start, end, per_page, and page. Pass include=metadata to include HealthKit metadata or include=hk_device to include HealthKit device details. Raw readings exclude samples deleted from Apple Health and samples superseded by deduplication.

Query parameters

All list endpoints support the following parameters:

For timestamp-backed endpoints, date-only start and end values are interpreted as full calendar-day boundaries in your profile timezone. Date-backed Apple Health aggregate endpoints and Oura daily endpoints compare against the stored date value directly.

On /whoop/daily, date remains the legacy cycle-end date for closed cycles; use cycle_start_date and cycle_end_date when you need explicit local cycle dates. If the user's current local-day cycle is still open, the endpoint may include it with is_partial: true and cycle_end_date: null. For morning automations, /whoop/daily is the canonical endpoint for deciding whether today's WHOOP recovery and sleep row is usable: select the row where cycle_start_date equals the user's local date and require both recovery_score and sleep_duration_minutes.

WHOOP recovery freshness

Use /whoop/recovery-status as advisory sync metadata only. It is useful when an automation needs to know whether VitalTrends recently checked, changed, or received upstream recovery data, but it is not a current-day completeness gate. Its latest_recovery and latest_cycle summaries use raw WHOOP cycle timestamps and do not apply the /whoop/daily sleep wake-day normalization for open cycles. last_recovery_data_changed_at advances only when stored recovery values change. last_recovery_synced_at advances when VitalTrends checks/applies recovery data, even if values are unchanged.

curl -s "https://vitaltrends.net/api/v1/whoop/recovery-status" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq .

{
  "data": {
    "connected": true,
    "needs_reconnection": false,
    "latest_recovery": {
      "cycle_id": "123e4567-e89b-12d3-a456-426614174000",
      "cycle_start_date": "2026-05-08",
      "cycle_end_date": "2026-05-09",
      "recovery_score": 82,
      "hrv_rmssd_milli": 68.4,
      "resting_heart_rate": 48,
      "recovery_synced_at": "2026-05-09T07:06:00+00:00",
      "recovery_data_changed_at": "2026-05-09T07:06:00+00:00",
      "whoop_recovery_updated_at": "2026-05-09T07:05:00+00:00"
    },
    "latest_cycle": {
      "cycle_id": "123e4567-e89b-12d3-a456-426614174000",
      "cycle_start_date": "2026-05-08",
      "cycle_end_date": "2026-05-09",
      "recovery_score": 82,
      "hrv_rmssd_milli": 68.4,
      "resting_heart_rate": 48,
      "recovery_synced_at": "2026-05-09T07:06:00+00:00",
      "recovery_data_changed_at": "2026-05-09T07:06:00+00:00",
      "whoop_recovery_updated_at": "2026-05-09T07:05:00+00:00"
    },
    "last_recovery_synced_at": "2026-05-09T07:06:00+00:00",
    "last_recovery_data_changed_at": "2026-05-09T07:06:00+00:00",
    "last_whoop_recovery_updated_at": "2026-05-09T07:05:00+00:00",
    "is_recovery_data_stale": false,
    "stale_after_hours": 24
  }
}

If is_recovery_data_stale is true or last_recovery_data_changed_at is more than 24 hours old, treat recovery freshness as uncertain and try again later. Do not conclude that today's recovery or sleep row is missing until you have checked /whoop/daily for the user's current local cycle_start_date. Opening the VitalTrends WHOOP dashboard also triggers a small recent-window WHOOP refresh when the latest recovery appears stale.

WHOOP daily date is the legacy cycle-end date for closed cycles; use cycle_start_date, cycle_end_date, and is_partial when you need explicit local cycle boundaries. WHOOP workout fields ending in _milli are durations in milliseconds, and kilojoule is energy in kilojoules.

Oura duration fields are returned in the units provided by Oura. Sleep durations are seconds; workout distance is meters; calorie fields are kilocalories.

On /oura/workouts, source is Oura's own workout source value. For example, confirmed means the workout was saved in Oura after confirmation in the Oura app. It is not a VitalTrends confidence score or a cross-device verification status. Other common values include autodetected, manual, and workout_heart_rate.

Withings measurement fields ending in _kg are stored in kilograms, and fat_ratio_pct is a percentage. Empty Withings fields mean the connected device did not provide that metric for the measurement, not that VitalTrends rejected it.

Apple Health source is the HealthKit device or app label that wrote the sample, not a confidence or verification status. Pass include=metadata on /apple-health?type=<type> to see sleep stages and workout details. For wrist temperature, request /apple-health?type=sleeping_wrist_temp. For cumulative daily metrics such as steps, distance, and energy, VitalTrends avoids double-counting by choosing the largest per-source daily total by default.

Glucose data currently comes from Apple Health blood_glucose samples. Use /glucose for dashboard-ready analytics and /glucose/readings for individual raw CGM readings. Use /apple-health?type=blood_glucose only when you want processed Apple Health aggregate rows in the generic Apple Health response shape.

Example request

curl -s "https://vitaltrends.net/api/v1/whoop/daily?start=2024-01-01&per_page=7" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq .

curl -s "https://vitaltrends.net/api/v1/oura/daily-readiness?start=2026-05-01&per_page=7" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq .

Example response

{
  "data": [
    {
      "date": "2024-01-07",
      "cycle_start_date": "2024-01-06",
      "cycle_end_date": "2024-01-07",
      "is_partial": false,
      "recovery_score": 82,
      "hrv_rmssd_milli": 68.4,
      "resting_heart_rate": 48,
      "sleep_performance_pct": 89,
      "sleep_duration_minutes": 450,
      "strain": 12.4,
      "whoop_recovery_updated_at": "2024-01-07T07:05:00+00:00",
      "recovery_synced_at": "2024-01-07T07:06:00+00:00",
      "recovery_data_changed_at": "2024-01-07T07:06:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 7,
    "total": 7,
    "from": 1,
    "to": 7
  }
}

Rate limits

The API allows 120 requests per minute per API key. If you exceed the limit, requests return 429 Too Many Requests with a Retry-After header.

Response caching

GET /apple-health?type=<type> is cached for 5 minutes per user and exact query string, including filters such as start, end, page, per_page, and include. The response includes Cache-Control: private, max-age=300. This cache is intended for repeated API reads and does not change the API rate limit.

Error responses

Need an endpoint that is not listed here? Get in touch and we will consider adding it.