Terra
App · 21 actions
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.
Actions
| Action | What it does |
|---|---|
| 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. |
| 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. |
| Create workout template | Store a structured workout (warm-up, intervals, cool-down...) to plan onto people's calendars with 'Plan workout'. |
| Delete planned workout | Remove a planned workout from someone's calendar and their device. |
| Delete workout template | Delete a workout template, and every planned workout made from it, from people's calendars and devices too. |
| Disconnect user | Disconnect someone's wearable: Terra stops reading it and deletes everything it holds for that connection. |
| Find users by reference ID | Find every connection made under one of your reference IDs, such as a customer's Garmin and their Oura. |
| 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. |
| Get athlete profile | Get the profile someone's provider holds for them: name, email, age, sex, date of birth and location, where shared. |
| 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. |
| 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. |
| Get menstruation | Get someone's cycle tracking over a date range (up to 31 days): cycle day, phase, period dates and predicted cycle length. |
| Get nutrition | Get what someone logged eating and drinking over a date range (up to 31 days): calories, protein, carbs, fat, meals and water. |
| 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. |
| Get user | Get one connection: its provider, reference ID, whether it is still connected, and when Terra last read new data from it. |
| List planned workouts | List someone's planned workouts, including ones they set up in their device's own app. |
| 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. |
| List users | List the people who have connected a wearable, one connection each, with the provider and your reference ID. |
| List workout templates | List the workout templates stored in your Terra account. |
| Plan workout | Put a workout template on someone's calendar for a day. |
| Reschedule planned workout | Move a workout planned through Terra to another day, on the calendar and the person's device. |
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_idtext - 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
providerstext - 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_urltext - Where to send the person once they've connected.
- Page if connecting fails
auth_failure_redirect_urltext - Where to send the person if connecting fails or they cancel.
- Allow several devices
multi_authtrue/false - Keep the person on the page after each connection so they can connect more than one device.Default:
false.
Outputs
expires_innumber- Seconds the link works for
reference_idtext- The reference ID given, if any
session_idtext- Terra's session ID
urltext- The link to send the person
Example output
{
"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
providertextRequired - Which one they connect. Pick it, or type its code.
- Reference ID
reference_idtext - 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_urltext - Where to send the person once they've connected.
- Page if connecting fails
auth_failure_redirect_urltext - Where to send the person if connecting fails or they cancel.
Outputs
auth_urltext- The provider's sign-in link to send the person
providertext- The provider code
reference_idtext- The reference ID given, if any
terra_user_idtext- The Terra user ID the connection will have
Example output
{
"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
nametextRequired - The workout's name, shown on the person's device.
- Sport
sporttextRequired - 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_blockslistRequired - 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
descriptiontext - A note on the workout, shown with it.
- Where
environmenttext - Indoors, outdoors or in a pool.One of:
indoor,outdoor,pool.
Outputs
nametext- Its name
workout_idtext- The new template's ID
Example output
{
"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_idtextRequired - The planned workout's ID, from 'Plan workout' or 'List planned workouts'.
- User
terra_user_idtextRequired - The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
Outputs
deletedtrue/false- Always true once deleted
planned_workout_idtext- The planned workout deleted
Example output
{
"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_idtextRequired - The workout template. Pick one, or give its ID from an earlier step.
Outputs
deletedtrue/false- Always true once deleted
workout_idtext- The template deleted
Example output
{
"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_idtextRequired - The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
Outputs
disconnectedtrue/false- Always true once disconnected
terra_user_idtext- The connection disconnected
Example output
{
"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_idtextRequired - The reference ID given when they connected.
Outputs
countnumber- How many
reference_idtext- The reference ID
userslist- The connections
Example output
{
"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_idtextRequired - The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
- From
start_datedateRequired - The first day to read.
- To
end_datedate - The last day to read, at most 31 days after the first. Leave empty to read up to today.
- Include samples
with_samplestrue/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
countnumber- How many
datalist- The workouts
userobject- The person's connection
Example output
{
"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_idtextRequired - The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
Outputs
athleteobject- The profile
userobject- The person's connection
Example output
{
"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_idtextRequired - The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
- From
start_datedateRequired - The first day to read.
- To
end_datedate - The last day to read, at most 31 days after the first. Leave empty to read up to today.
- Include samples
with_samplestrue/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
countnumber- How many
datalist- One record per day
userobject- The person's connection
Example output
{
"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_idtextRequired - The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
- From
start_datedateRequired - The first day to read.
- To
end_datedate - The last day to read, at most 31 days after the first. Leave empty to read up to today.
- Include samples
with_samplestrue/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
countnumber- How many
datalist- One summary per day
userobject- The person's connection
Example output
{
"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_idtextRequired - The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
- From
start_datedateRequired - The first day to read.
- To
end_datedate - The last day to read, at most 31 days after the first. Leave empty to read up to today.
- Include samples
with_samplestrue/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
countnumber- How many
datalist- One record per day
userobject- The person's connection
Example output
{
"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_idtextRequired - The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
- From
start_datedateRequired - The first day to read.
- To
end_datedate - The last day to read, at most 31 days after the first. Leave empty to read up to today.
- Include samples
with_samplestrue/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
countnumber- How many
datalist- One record per day
userobject- The person's connection
Example output
{
"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_idtextRequired - The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
- From
start_datedateRequired - The first day to read.
- To
end_datedate - The last day to read, at most 31 days after the first. Leave empty to read up to today.
- Include samples
with_samplestrue/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
countnumber- How many
datalist- The sleep sessions
userobject- The person's connection
Example output
{
"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_idtextRequired - The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
Outputs
is_authenticatedtrue/false- Whether the connection still works
userobject- The connection
Example output
{
"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_idtextRequired - The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
- From
start_datedate - The first day to include.
- To
end_datedate - The last day to include.
Outputs
countnumber- How many
planned_workoutslist- The planned workouts
provider_data_missingtrue/false- True when the device's platform couldn't be read, so workouts set up there are missing
Example output
{
"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_sdktrue/false - Also list Apple Health, Health Connect and Samsung Health, which connect through a phone app.Default:
false.
Outputs
countnumber- How many
providerslist- The wearables and apps
Example output
{
"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
pagenumber - Which page, starting at 0 (the default).At least 0.
- Page size
per_pagenumber - How many per page, 1 to 500. Defaults to 100.From 1 to 500.
Outputs
countnumber- How many on this page
max_pagenumber- The last page's number at this page size
next_pagenumber- The next page's number; empty on the last page
userslist- The connections
Example output
{
"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
countnumber- How many
templateslist- The templates
Example output
{
"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_idtextRequired - The workout template. Pick one, or give its ID from an earlier step.
- User
terra_user_idtextRequired - The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
- Date
planned_datedateRequired - The day to do the workout.
- Max heart rate
max_heart_ratenumber - Their maximum heart rate in beats per minute, for percentage-of-max targets.
- Threshold heart rate
threshold_heart_ratenumber - Their threshold heart rate in beats per minute.
- FTP
ftpnumber - Their functional threshold power in watts, for cycling power targets.
- Threshold speed
threshold_speednumber - Their threshold speed in metres per second.
- Pool length
pool_length_metersnumber - Pool length in metres, for swims. Replaces the template's.
Outputs
planned_datetext- The day, YYYY-MM-DD
planned_workout_idtext- The planned workout's ID
provider_workout_idtext- Its ID on the device's platform, if sent there
warningslist- What the device couldn't show exactly as written
Example output
{
"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_idtextRequired - The planned workout's ID, from 'Plan workout' or 'List planned workouts'.
- User
terra_user_idtextRequired - The person's connection in Terra. Pick one, or give its Terra user ID from an earlier step.
- New date
planned_datedateRequired - The day to move it to.
Outputs
planned_workoutobject- The planned workout, moved
Example output
{
"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"
}
}