@spec multiple_workout(start_date(), end_date(), next_token(), opts()) ::
  workout_response()

Retrieves multiple workout records for a specified date range.

Returns paginated workout data including both auto-detected and manually logged workouts. This endpoint is essential for comprehensive exercise and activity tracking.

Parameters

• start_date - The start date for the data range (Date struct, inclusive)
• end_date - The end date for the data range (Date struct, inclusive)
• next_token - Optional token for pagination (from previous response)
• opts - Optional keyword list of additional parameters

Options

• :timeout - Request timeout in milliseconds (defaults to configured timeout)

Returns

• {:ok, response} - Success with workout data and optional next_token
• {:error, reason} - Error with details about what went wrong

Examples

# Get workouts for January 2025
{:ok, workouts} = ExOura.Workout.multiple_workout(
  ~D[2025-01-01],
  ~D[2025-01-31]
)

# Analyze workout patterns
workouts.data
|> Enum.group_by(& &1.activity)
|> Enum.each(fn {activity_type, workouts} ->
  count = length(workouts)
  avg_duration = workouts |> Enum.map(& &1.duration) |> Enum.sum() |> div(count)
  IO.puts("#{activity_type}: #{count} workouts, avg duration: #{avg_duration}s")
end)

# Filter high-intensity workouts
high_intensity_workouts = workouts.data
|> Enum.filter(fn workout ->
  workout.intensity == "high" or
  (workout.average_heart_rate && workout.average_heart_rate > 150)
end)

# Handle pagination for large date ranges
{:ok, page1} = ExOura.Workout.multiple_workout(
  ~D[2024-01-01],
  ~D[2024-12-31]
)

if page1.next_token do
  {:ok, page2} = ExOura.Workout.multiple_workout(
    ~D[2024-01-01],
    ~D[2024-12-31],
    page1.next_token
  )
end

Response Structure

The response contains:

• data - List of workout records
• next_token - Token for next page (nil if no more data)

Each workout record includes:

• id - Unique workout identifier
• activity - Type of activity (e.g., "walking", "running", "cycling")
• source - How the workout was detected ("autodetected", "manual", "confirmed")
• day - Date of the workout (YYYY-MM-DD)
• start_datetime - When the workout started
• end_datetime - When the workout ended
• duration - Workout duration in seconds
• intensity - Intensity level ("low", "medium", "high")
• calories - Calories burned during the workout
• average_heart_rate - Average heart rate (if available)
• maximum_heart_rate - Peak heart rate (if available)
• heart_rate_zones - Time spent in different HR zones
• motion_count - Movement intensity data

@spec single_workout(document_id(), opts()) :: single_workout_response()

Retrieves a single workout record by its document ID.

Use this function when you need detailed information about a specific workout session. This is useful for in-depth analysis of individual exercise sessions.

Parameters

• document_id - The unique identifier for the workout document
• opts - Optional keyword list of additional parameters

Options

• :timeout - Request timeout in milliseconds (defaults to configured timeout)

Returns

• {:ok, workout} - Success with single workout record
• {:error, reason} - Error with details (e.g., document not found)

Examples

# Get detailed workout information
{:ok, workout} = ExOura.Workout.single_workout("workout_2025-01-15T14-30-00")

IO.puts("Activity: #{workout.activity}")
IO.puts("Duration: #{workout.duration} seconds")
IO.puts("Calories: #{workout.calories}")
IO.puts("Average HR: #{workout.average_heart_rate} bpm")

# Analyze heart rate zones
case ExOura.Workout.single_workout("workout_id") do
  {:ok, workout} ->
    if workout.heart_rate_zones do
      IO.puts("Time in zones: #{inspect(workout.heart_rate_zones)}")
    end
  {:error, reason} ->
    IO.puts("Error: #{inspect(reason)}")
end

# Check workout source and intensity
{:ok, workout} = ExOura.Workout.single_workout("workout_id")

case {workout.source, workout.intensity} do
  {"autodetected", "high"} ->
    IO.puts("High-intensity workout automatically detected")
  {"manual", _} ->
    IO.puts("Manually logged workout")
  _ ->
    IO.puts("Regular detected workout")
end

Response Structure

Returns a single workout record with the same comprehensive metrics as described in multiple_workout/4, but without the pagination wrapper.

Workout Analysis Tips

• Use source to distinguish between auto-detected and manual workouts
• intensity provides a quick assessment of workout difficulty
• Heart rate data (when available) offers detailed cardiovascular insights
• Motion count can indicate movement patterns and workout variability