# Terra

> Read health and fitness data from your users' wearables through Terra (Garmin, Oura, Fitbit, WHOOP, Polar and more): send connection links, manage connections, get workouts, sleep, daily totals, body metrics and nutrition, and plan workouts onto their devices.

App · 21 actions. Web page: https://docs.lodol.com/docs/integrations/terra

## Actions

### Create connection link

Create a link to send someone so they can connect their wearable or health app: they pick it from Terra's list and sign in. The link works for 24 hours.

**Inputs**

- Reference ID (`reference_id`, text): Your own ID for the person, such as their email or customer ID. Terra keeps it on the connection, so you can find it later.
- Wearables to offer (`providers`, text): Only offer these, in this order. Pick one, or type codes separated by commas, such as GARMIN,OURA,FITBIT. Leave empty to offer every source enabled in your Terra dashboard.
- Page after connecting (`auth_success_redirect_url`, text): Where to send the person once they've connected.
- Page if connecting fails (`auth_failure_redirect_url`, text): Where to send the person if connecting fails or they cancel.
- Allow several devices (`multi_auth`, true/false): Keep the person on the page after each connection so they can connect more than one device. Default: `false`.

**Outputs**

- `expires_in` (number): Seconds the link works for
- `reference_id` (text): The reference ID given, if any
- `session_id` (text): Terra's session ID
- `url` (text): The link to send the person

**Example output**

```json
{
  "expires_in": 86400,
  "reference_id": "customer-1042",
  "session_id": "23dc2540-7139-44c6-8158-f81196e2cf2e",
  "url": "https://access.tryterra.co/widget/session/23dc2540-7139-44c6-8158-f81196e2cf2e"
}
```

### Create sign-in link for one wearable

Create a link that takes someone straight to one provider's sign-in page (Garmin, Oura, Fitbit...), skipping Terra's list. Returns their new Terra user ID too.

**Inputs**

- Wearable or app (`provider`, text, required): Which one they connect. Pick it, or type its code.
- Reference ID (`reference_id`, text): Your own ID for the person, such as their email or customer ID. Terra keeps it on the connection, so you can find it later.
- Page after connecting (`auth_success_redirect_url`, text): Where to send the person once they've connected.
- Page if connecting fails (`auth_failure_redirect_url`, text): Where to send the person if connecting fails or they cancel.

**Outputs**

- `auth_url` (text): The provider's sign-in link to send the person
- `provider` (text): The provider code
- `reference_id` (text): The reference ID given, if any
- `terra_user_id` (text): The Terra user ID the connection will have

**Example output**

```json
{
  "auth_url": "https://www.fitbit.com/oauth2/authorize?response_type=code&client_id=23BBG9&state=bLqqjPie9ptwoWm6VBxHCu6JkkoWJp",
  "provider": "FITBIT",
  "reference_id": "customer-1042",
  "terra_user_id": "23dc2540-7139-44c6-8158-f81196e2cf2e"
}
```

### Create workout template

Store a structured workout (warm-up, intervals, cool-down...) to plan onto people's calendars with 'Plan workout'. Needs Terra's Planned Workouts add-on.

**Inputs**

- Name (`name`, text, required): The workout's name, shown on the person's device.
- Sport (`sport`, text, required): What kind of workout it is. One of: `running`, `cycling`, `swimming`, `strength`, `rowing`, `yoga`, `pilates`, `cardio`, `trail_running` (Trail running), `mountain_biking` (Mountain biking), and 5 more.
- Steps (`step_blocks`, list, required): The workout's step blocks, in Terra's format. Each block has steps, each with a completion_condition and an intensity_type (warmup, active, rest, recovery or cooldown); a block with {"type": "reps", "value": 5} repeats 5 times. For a 10-minute run: [{"steps": [{"completion_condition": {"type": "time", "value": 600}, "intensity_type": "active"}]}]
- Description (`description`, text): A note on the workout, shown with it.
- Where (`environment`, text): Indoors, outdoors or in a pool. One of: `indoor`, `outdoor`, `pool`.

**Outputs**

- `name` (text): Its name
- `workout_id` (text): The new template's ID

**Example output**

```json
{
  "name": "5x3min HR intervals",
  "workout_id": "1024"
}
```

### Delete planned workout

Remove a planned workout from someone's calendar and their device.

**Inputs**

- Planned workout ID (`planned_workout_id`, text, required): The planned workout's ID, from 'Plan workout' or 'List planned workouts'.
- User (`terra_user_id`, text, required): The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.

**Outputs**

- `deleted` (true/false): Always true once deleted
- `planned_workout_id` (text): The planned workout deleted

**Example output**

```json
{
  "deleted": true,
  "planned_workout_id": "2048"
}
```

### Delete workout template

Delete a workout template, and every planned workout made from it, from people's calendars and devices too.

**Inputs**

- Workout template (`workout_id`, text, required): The workout template. Pick one, or give its ID from an earlier step.

**Outputs**

- `deleted` (true/false): Always true once deleted
- `workout_id` (text): The template deleted

**Example output**

```json
{
  "deleted": true,
  "workout_id": "1024"
}
```

### Disconnect user

Disconnect someone's wearable: Terra stops reading it and deletes everything it holds for that connection. They'd have to connect again to share data.

**Inputs**

- User (`terra_user_id`, text, required): The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.

**Outputs**

- `disconnected` (true/false): Always true once disconnected
- `terra_user_id` (text): The connection disconnected

**Example output**

```json
{
  "disconnected": true,
  "terra_user_id": "23dc2540-7139-44c6-8158-f81196e2cf2e"
}
```

### Find users by reference ID

Find every connection made under one of your reference IDs, such as a customer's Garmin and their Oura.

**Inputs**

- Reference ID (`reference_id`, text, required): The reference ID given when they connected.

**Outputs**

- `count` (number): How many
- `reference_id` (text): The reference ID
- `users` (list): The connections

**Example output**

```json
{
  "count": 1,
  "reference_id": "customer-1042",
  "users": [
    {
      "active": true,
      "created_at": "2026-10-01T09:30:00Z",
      "last_webhook_update": "2026-11-09T07:12:00Z",
      "provider": "GARMIN",
      "reference_id": "customer-1042",
      "scopes": "activity,sleep,daily",
      "user_id": "23dc2540-7139-44c6-8158-f81196e2cf2e"
    }
  ]
}
```

### Get activities

Get someone's workouts over a date range (up to 31 days): each with its type, start and end, distance, calories and heart rate.

**Inputs**

- User (`terra_user_id`, text, required): The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
- From (`start_date`, date, required): The first day to read.
- To (`end_date`, date): The last day to read, at most 31 days after the first. Leave empty to read up to today.
- Include samples (`with_samples`, true/false): Also return the minute-by-minute samples (heart rate, steps, GPS and so on), which can be large. Off by default. Default: `false`.

**Outputs**

- `count` (number): How many
- `data` (list): The workouts
- `user` (object): The person's connection

**Example output**

```json
{
  "count": 1,
  "data": [
    {
      "TSS_data": {},
      "active_durations_data": {
        "activity_seconds": 2562,
        "inactivity_seconds": 0,
        "low_intensity_seconds": 300,
        "moderate_intensity_seconds": 1500,
        "rest_seconds": 0,
        "vigorous_intensity_seconds": 762
      },
      "calories_data": {
        "BMR_calories": 72,
        "net_activity_calories": 540,
        "net_intake_calories": 0,
        "total_burned_calories": 612
      },
      "data_enrichment": {},
      "device_data": {
        "manufacturer": "Garmin",
        "name": "Forerunner 265",
        "software_version": "19.18"
      },
      "distance_data": {
        "detailed": {},
        "summary": {
          "distance_meters": 8012.4,
          "elevation": {},
          "floors_climbed": 0,
          "steps": 7350
        }
      },
      "heart_rate_data": {
        "detailed": {},
        "summary": {
          "avg_hr_bpm": 142,
          "avg_hrv_rmssd": 48.5,
          "avg_hrv_sdnn": 61.2,
          "max_hr_bpm": 171,
          "min_hr_bpm": 96,
          "resting_hr_bpm": 52
        }
      },
      "lap_data": {},
      "metadata": {
        "city": "Leeds",
        "country": "United Kingdom",
        "end_time": "2026-11-09T07:44:53.000000+00:00",
        "name": "Morning Run",
        "start_time": "2026-11-09T07:02:11.000000+00:00",
        "summary_id": "18392018472",
        "type": 8,
        "upload_type": 1
      },
      "movement_data": {},
      "position_data": {},
      "power_data": {},
      "strength_data": {}
    }
  ],
  "user": {
    "active": true,
    "created_at": "2026-10-01T09:30:00Z",
    "last_webhook_update": "2026-11-09T07:12:00Z",
    "provider": "GARMIN",
    "reference_id": "customer-1042",
    "scopes": "activity,sleep,daily",
    "user_id": "23dc2540-7139-44c6-8158-f81196e2cf2e"
  }
}
```

### Get athlete profile

Get the profile someone's provider holds for them: name, email, age, sex, date of birth and location, where shared.

**Inputs**

- User (`terra_user_id`, text, required): The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.

**Outputs**

- `athlete` (object): The profile
- `user` (object): The person's connection

**Example output**

```json
{
  "athlete": {
    "account_creation_date": "2019-06-02",
    "age": 34,
    "bio": "",
    "city": "Leeds",
    "country": "GB",
    "date_of_birth": "1992-04-18",
    "email": "sam@example.com",
    "first_name": "Sam",
    "gender": "female",
    "last_name": "Taylor",
    "provider_user_id": "a8f1c2",
    "sex": "female",
    "state": ""
  },
  "user": {
    "active": true,
    "created_at": "2026-10-01T09:30:00Z",
    "last_webhook_update": "2026-11-09T07:12:00Z",
    "provider": "GARMIN",
    "reference_id": "customer-1042",
    "scopes": "activity,sleep,daily",
    "user_id": "23dc2540-7139-44c6-8158-f81196e2cf2e"
  }
}
```

### Get body metrics

Get someone's body measurements over a date range (up to 31 days): weight, body fat, BMI, blood pressure, glucose and temperature, as their devices record them.

**Inputs**

- User (`terra_user_id`, text, required): The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
- From (`start_date`, date, required): The first day to read.
- To (`end_date`, date): The last day to read, at most 31 days after the first. Leave empty to read up to today.
- Include samples (`with_samples`, true/false): Also return the minute-by-minute samples (heart rate, steps, GPS and so on), which can be large. Off by default. Default: `false`.

**Outputs**

- `count` (number): How many
- `data` (list): One record per day
- `user` (object): The person's connection

**Example output**

```json
{
  "count": 1,
  "data": [
    {
      "blood_pressure_data": {},
      "device_data": {
        "manufacturer": "Withings",
        "name": "Body Smart",
        "software_version": "2.4"
      },
      "glucose_data": {},
      "heart_data": {},
      "hydration_data": {},
      "measurements_data": {
        "day_avg_bmi": 22.4,
        "day_avg_bodyfat_percentage": 17.2,
        "day_avg_height_cm": 179,
        "day_avg_weight_kg": 71.8,
        "measurements": [
          {
            "measurement_time": "2026-11-09T07:00:00+00:00",
            "weight_kg": 71.8
          }
        ]
      },
      "metadata": {
        "end_time": "2026-11-10T00:00:00.000000+00:00",
        "start_time": "2026-11-09T00:00:00.000000+00:00"
      },
      "oxygen_data": {},
      "temperature_data": {}
    }
  ],
  "user": {
    "active": true,
    "created_at": "2026-10-01T09:30:00Z",
    "last_webhook_update": "2026-11-09T07:12:00Z",
    "provider": "GARMIN",
    "reference_id": "customer-1042",
    "scopes": "activity,sleep,daily",
    "user_id": "23dc2540-7139-44c6-8158-f81196e2cf2e"
  }
}
```

### Get daily summaries

Get someone's day-by-day totals over a date range (up to 31 days): steps, distance, calories, heart rate, active time and scores.

**Inputs**

- User (`terra_user_id`, text, required): The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
- From (`start_date`, date, required): The first day to read.
- To (`end_date`, date): The last day to read, at most 31 days after the first. Leave empty to read up to today.
- Include samples (`with_samples`, true/false): Also return the minute-by-minute samples (heart rate, steps, GPS and so on), which can be large. Off by default. Default: `false`.

**Outputs**

- `count` (number): How many
- `data` (list): One summary per day
- `user` (object): The person's connection

**Example output**

```json
{
  "count": 1,
  "data": [
    {
      "active_durations_data": {
        "activity_seconds": 5400,
        "inactivity_seconds": 41000,
        "low_intensity_seconds": 2700,
        "moderate_intensity_seconds": 1800,
        "rest_seconds": 28800,
        "vigorous_intensity_seconds": 900
      },
      "calories_data": {
        "BMR_calories": 1790,
        "net_activity_calories": 920,
        "net_intake_calories": 0,
        "total_burned_calories": 2710
      },
      "data_enrichment": {},
      "device_data": {
        "manufacturer": "Garmin",
        "name": "Forerunner 265",
        "software_version": "19.18"
      },
      "distance_data": {
        "distance_meters": 9120.5,
        "elevation": {},
        "floors_climbed": 9,
        "steps": 11842
      },
      "heart_rate_data": {
        "detailed": {},
        "summary": {
          "avg_hr_bpm": 142,
          "avg_hrv_rmssd": 48.5,
          "avg_hrv_sdnn": 61.2,
          "max_hr_bpm": 171,
          "min_hr_bpm": 96,
          "resting_hr_bpm": 52
        }
      },
      "metadata": {
        "end_time": "2026-11-10T00:00:00.000000+00:00",
        "start_time": "2026-11-09T00:00:00.000000+00:00",
        "upload_type": 1
      },
      "oxygen_data": {},
      "scores": {
        "activity": 82,
        "recovery": 67,
        "sleep": 88
      },
      "strain_data": {},
      "stress_data": {}
    }
  ],
  "user": {
    "active": true,
    "created_at": "2026-10-01T09:30:00Z",
    "last_webhook_update": "2026-11-09T07:12:00Z",
    "provider": "GARMIN",
    "reference_id": "customer-1042",
    "scopes": "activity,sleep,daily",
    "user_id": "23dc2540-7139-44c6-8158-f81196e2cf2e"
  }
}
```

### Get menstruation

Get someone's cycle tracking over a date range (up to 31 days): cycle day, phase, period dates and predicted cycle length.

**Inputs**

- User (`terra_user_id`, text, required): The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
- From (`start_date`, date, required): The first day to read.
- To (`end_date`, date): The last day to read, at most 31 days after the first. Leave empty to read up to today.
- Include samples (`with_samples`, true/false): Also return the minute-by-minute samples (heart rate, steps, GPS and so on), which can be large. Off by default. Default: `false`.

**Outputs**

- `count` (number): How many
- `data` (list): One record per day
- `user` (object): The person's connection

**Example output**

```json
{
  "count": 1,
  "data": [
    {
      "menstruation_data": {
        "current_phase": "follicular",
        "cycle_length_days": 28,
        "day_in_cycle": 9,
        "menstruation_flow": {},
        "period_length_days": 5,
        "period_start_date": "2026-11-01",
        "predicted_cycle_length_days": 28
      },
      "metadata": {
        "end_time": "2026-11-10T00:00:00.000000+00:00",
        "start_time": "2026-11-09T00:00:00.000000+00:00"
      }
    }
  ],
  "user": {
    "active": true,
    "created_at": "2026-10-01T09:30:00Z",
    "last_webhook_update": "2026-11-09T07:12:00Z",
    "provider": "GARMIN",
    "reference_id": "customer-1042",
    "scopes": "activity,sleep,daily",
    "user_id": "23dc2540-7139-44c6-8158-f81196e2cf2e"
  }
}
```

### Get nutrition

Get what someone logged eating and drinking over a date range (up to 31 days): calories, protein, carbs, fat, meals and water.

**Inputs**

- User (`terra_user_id`, text, required): The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
- From (`start_date`, date, required): The first day to read.
- To (`end_date`, date): The last day to read, at most 31 days after the first. Leave empty to read up to today.
- Include samples (`with_samples`, true/false): Also return the minute-by-minute samples (heart rate, steps, GPS and so on), which can be large. Off by default. Default: `false`.

**Outputs**

- `count` (number): How many
- `data` (list): One record per day
- `user` (object): The person's connection

**Example output**

```json
{
  "count": 1,
  "data": [
    {
      "drink_samples": [],
      "meals": [
        {
          "name": "Porridge",
          "type": 1
        }
      ],
      "metadata": {
        "end_time": "2026-11-10T00:00:00.000000+00:00",
        "start_time": "2026-11-09T00:00:00.000000+00:00"
      },
      "summary": {
        "drink_ml": 2300,
        "macros": {
          "calories": 2240,
          "carbohydrates_g": 251,
          "fat_g": 74,
          "fiber_g": 31,
          "protein_g": 132,
          "sodium_mg": 2100,
          "sugar_g": 58
        },
        "micros": {},
        "water_ml": 1800
      }
    }
  ],
  "user": {
    "active": true,
    "created_at": "2026-10-01T09:30:00Z",
    "last_webhook_update": "2026-11-09T07:12:00Z",
    "provider": "GARMIN",
    "reference_id": "customer-1042",
    "scopes": "activity,sleep,daily",
    "user_id": "23dc2540-7139-44c6-8158-f81196e2cf2e"
  }
}
```

### Get sleep

Get someone's sleep sessions over a date range (up to 31 days): when they slept, time in deep, light and REM sleep, efficiency and heart rate.

**Inputs**

- User (`terra_user_id`, text, required): The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
- From (`start_date`, date, required): The first day to read.
- To (`end_date`, date): The last day to read, at most 31 days after the first. Leave empty to read up to today.
- Include samples (`with_samples`, true/false): Also return the minute-by-minute samples (heart rate, steps, GPS and so on), which can be large. Off by default. Default: `false`.

**Outputs**

- `count` (number): How many
- `data` (list): The sleep sessions
- `user` (object): The person's connection

**Example output**

```json
{
  "count": 1,
  "data": [
    {
      "data_enrichment": {},
      "device_data": {
        "manufacturer": "Garmin",
        "name": "Forerunner 265",
        "software_version": "19.18"
      },
      "heart_rate_data": {
        "detailed": {},
        "summary": {
          "avg_hr_bpm": 142,
          "avg_hrv_rmssd": 48.5,
          "avg_hrv_sdnn": 61.2,
          "max_hr_bpm": 171,
          "min_hr_bpm": 96,
          "resting_hr_bpm": 52
        }
      },
      "metadata": {
        "end_time": "2026-11-09T06:41:00.000000+00:00",
        "is_nap": false,
        "start_time": "2026-11-08T23:04:00.000000+00:00",
        "summary_id": "sleep-20261109",
        "upload_type": 1
      },
      "readiness_data": {},
      "respiration_data": {},
      "scores": {},
      "sleep_durations_data": {
        "asleep": {
          "duration_REM_sleep_state_seconds": 6120,
          "duration_asleep_state_seconds": 24960,
          "duration_deep_sleep_state_seconds": 5040,
          "duration_light_sleep_state_seconds": 13800
        },
        "awake": {},
        "other": {},
        "sleep_efficiency": 0.91
      },
      "temperature_data": {}
    }
  ],
  "user": {
    "active": true,
    "created_at": "2026-10-01T09:30:00Z",
    "last_webhook_update": "2026-11-09T07:12:00Z",
    "provider": "GARMIN",
    "reference_id": "customer-1042",
    "scopes": "activity,sleep,daily",
    "user_id": "23dc2540-7139-44c6-8158-f81196e2cf2e"
  }
}
```

### Get user

Get one connection: its provider, reference ID, whether it is still connected, and when Terra last read new data from it.

**Inputs**

- User (`terra_user_id`, text, required): The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.

**Outputs**

- `is_authenticated` (true/false): Whether the connection still works
- `user` (object): The connection

**Example output**

```json
{
  "is_authenticated": true,
  "user": {
    "active": true,
    "created_at": "2026-10-01T09:30:00Z",
    "last_polled_at": "2026-11-09T07:15:00Z",
    "last_webhook_update": "2026-11-09T07:12:00Z",
    "most_recent_data_at": "2026-11-09T06:41:00Z",
    "provider": "GARMIN",
    "reference_id": "customer-1042",
    "scopes": "activity,sleep,daily",
    "user_id": "23dc2540-7139-44c6-8158-f81196e2cf2e"
  }
}
```

### List planned workouts

List someone's planned workouts, including ones they set up in their device's own app. Without dates, those cover the last 30 days; give dates to see upcoming ones.

**Inputs**

- User (`terra_user_id`, text, required): The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
- From (`start_date`, date): The first day to include.
- To (`end_date`, date): The last day to include.

**Outputs**

- `count` (number): How many
- `planned_workouts` (list): The planned workouts
- `provider_data_missing` (true/false): True when the device's platform couldn't be read, so workouts set up there are missing

**Example output**

```json
{
  "count": 1,
  "planned_workouts": [
    {
      "completed_at": null,
      "created_at": "2026-11-10T09:00:00Z",
      "is_external": false,
      "last_updated_at": "2026-11-10T09:00:00Z",
      "planned_date": "2026-11-17",
      "planned_workout_id": "2048",
      "provider_workout_id": "1290033412",
      "warnings": [],
      "workout": {
        "description": "Intervals at 85-90% of max heart rate.",
        "environment": "outdoor",
        "estimated_distance_meters": 6000,
        "estimated_duration_seconds": 1800,
        "name": "5x3min HR intervals",
        "sport": "running",
        "step_blocks": [
          {
            "completion_condition": {
              "type": "open"
            },
            "steps": [
              {
                "completion_condition": {
                  "type": "time",
                  "value": 300
                },
                "intensity_type": "warmup"
              }
            ]
          }
        ],
        "workout_id": "1024"
      },
      "workout_id": "1024"
    }
  ],
  "provider_data_missing": false
}
```

### List supported wearables and apps

List the wearables and health apps Terra connects to, with their codes, names, logos, the data each gives, and whether each is enabled for your account.

**Inputs**

- Include phone-only apps (`include_sdk`, true/false): Also list Apple Health, Health Connect and Samsung Health, which connect through a phone app. Default: `false`.

**Outputs**

- `count` (number): How many
- `providers` (list): The wearables and apps

**Example output**

```json
{
  "count": 1,
  "providers": [
    {
      "enabled": true,
      "icon": "https://api.tryterra.co/v2/static/assets/garmin.png",
      "name": "Garmin",
      "provider": "GARMIN",
      "setup": "default",
      "types": {
        "activity": true,
        "daily": true,
        "sleep": true
      }
    }
  ]
}
```

### List users

List the people who have connected a wearable, one connection each, with the provider and your reference ID. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Page (`page`, number): Which page, starting at 0 (the default). At least 0.
- Page size (`per_page`, number): How many per page, 1 to 500. Defaults to 100. From 1 to 500.

**Outputs**

- `count` (number): How many on this page
- `max_page` (number): The last page's number at this page size
- `next_page` (number): The next page's number; empty on the last page
- `users` (list): The connections

**Example output**

```json
{
  "count": 1,
  "max_page": 0,
  "next_page": null,
  "users": [
    {
      "active": true,
      "created_at": "2026-10-01T09:30:00Z",
      "last_webhook_update": "2026-11-09T07:12:00Z",
      "provider": "GARMIN",
      "reference_id": "customer-1042",
      "scopes": "activity,sleep,daily",
      "user_id": "23dc2540-7139-44c6-8158-f81196e2cf2e"
    }
  ]
}
```

### List workout templates

List the workout templates stored in your Terra account. Needs Terra's Planned Workouts add-on.

**Inputs**: None.

**Outputs**

- `count` (number): How many
- `templates` (list): The templates

**Example output**

```json
{
  "count": 1,
  "templates": [
    {
      "description": "Intervals at 85-90% of max heart rate.",
      "environment": "outdoor",
      "estimated_distance_meters": 6000,
      "estimated_duration_seconds": 1800,
      "name": "5x3min HR intervals",
      "sport": "running",
      "step_blocks": [
        {
          "completion_condition": {
            "type": "open"
          },
          "steps": [
            {
              "completion_condition": {
                "type": "time",
                "value": 300
              },
              "intensity_type": "warmup"
            }
          ]
        }
      ],
      "workout_id": "1024"
    }
  ]
}
```

### Plan workout

Put a workout template on someone's calendar for a day. Terra sends it to their device (Garmin, Wahoo, COROS...), personalised with any heart rate, power or pace figures given.

**Inputs**

- Workout template (`workout_id`, text, required): The workout template. Pick one, or give its ID from an earlier step.
- User (`terra_user_id`, text, required): The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
- Date (`planned_date`, date, required): The day to do the workout.
- Max heart rate (`max_heart_rate`, number): Their maximum heart rate in beats per minute, for percentage-of-max targets.
- Threshold heart rate (`threshold_heart_rate`, number): Their threshold heart rate in beats per minute.
- FTP (`ftp`, number): Their functional threshold power in watts, for cycling power targets.
- Threshold speed (`threshold_speed`, number): Their threshold speed in metres per second.
- Pool length (`pool_length_meters`, number): Pool length in metres, for swims. Replaces the template's.

**Outputs**

- `planned_date` (text): The day, YYYY-MM-DD
- `planned_workout_id` (text): The planned workout's ID
- `provider_workout_id` (text): Its ID on the device's platform, if sent there
- `warnings` (list): What the device couldn't show exactly as written

**Example output**

```json
{
  "planned_date": "2026-11-17",
  "planned_workout_id": "2048",
  "provider_workout_id": "1290033412",
  "warnings": []
}
```

### Reschedule planned workout

Move a workout planned through Terra to another day, on the calendar and the person's device.

**Inputs**

- Planned workout ID (`planned_workout_id`, text, required): The planned workout's ID, from 'Plan workout' or 'List planned workouts'.
- User (`terra_user_id`, text, required): The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
- New date (`planned_date`, date, required): The day to move it to.

**Outputs**

- `planned_workout` (object): The planned workout, moved

**Example output**

```json
{
  "planned_workout": {
    "completed_at": null,
    "created_at": "2026-11-10T09:00:00Z",
    "is_external": false,
    "last_updated_at": "2026-11-10T09:00:00Z",
    "planned_date": "2026-11-19",
    "planned_workout_id": "2048",
    "provider_workout_id": "1290033412",
    "warnings": [],
    "workout": {
      "description": "Intervals at 85-90% of max heart rate.",
      "environment": "outdoor",
      "estimated_distance_meters": 6000,
      "estimated_duration_seconds": 1800,
      "name": "5x3min HR intervals",
      "sport": "running",
      "step_blocks": [
        {
          "completion_condition": {
            "type": "open"
          },
          "steps": [
            {
              "completion_condition": {
                "type": "time",
                "value": 300
              },
              "intensity_type": "warmup"
            }
          ]
        }
      ],
      "workout_id": "1024"
    },
    "workout_id": "1024"
  }
}
```
