REST API Endpoints

NextSupported integrations

Was this helpful?

Get list of available integrations

get

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/integrations'

200

{
  "providers": [
    "FITBIT"
  ],
  "sdk_resource": [
    "APPLE"
  ],
  "status": "success"
}

Returns list of all available integrations on the API

Get detailed list of integrations

get

Retrieve a detailed list of supported integrations, optionally filtered by the developer's enabled integrations and the requirement for SDK usage.

Query parameters

sdkbooleanoptional

If true, allows SDK integrations to be included in the response.

Header parameters

dev-idstringoptional

Developer ID to filter the integrations list based on the developer's enabled integrations.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/integrations/detailed'

200

{
  "status": "success",
  "providers": [
    {
      "provider": "MAPMYFITNESS",
      "name": "MapMyFitness",
      "icon": "https://api.tryterra.co/v2/static/assets/img/app_icons/mapmyfitness.webp",
      "setup": "API_KEYS_MANAGED",
      "enabled": true,
      "types": {
        "activity": true,
        "body": false,
        "nutrition": false,
        "daily": false,
        "sleep": false,
        "menstruation": false
      }
    }
  ]
}

Successful response containing a list of integrations.

Deauthenticates a user and deletes any cached data for them

delete

Deletes all records of the user on Terra's end, revoking Terra's access to their data

Authorizations

Query parameters

user_idstringrequired

user_id to deauthenticate for

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.tryterra.co/v2/auth/deauthenticateUser?user_id=text' \
  --header 'x-api-key: text' \
  --header 'dev-id: text'

200

404

{
  "status": "success"
}

Returned when authentication link could be successfully generated

get

Used to query for information on one Terra user ID, or to query for all registered Terra User objects under one reference ID

Authorizations

Query parameters

user_idstringoptional

user ID to query for

reference_idstringoptional

reference ID to query for

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/userInfo' \
  --header 'x-api-key: text' \
  --header 'dev-id: text'

200

400

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "status": "success",
  "is_authenticated": true
}

Returned when the provided resources are found

Retrieve user profile info for a given user ID

get

Fetches relevant profile info such as first & last name, birth date etc. for a given user ID

Authorizations

Query parameters

user_idstringrequired

user ID to query data for

to_webhookbooleanoptional

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/athlete?user_id=text' \
  --header 'x-api-key: text' \
  --header 'dev-id: text'

200

400

401

404

{
  "athlete": {
    "gender": "male",
    "state": "California",
    "bio": "Passionate runner and cyclist",
    "age": "28",
    "country": "United States",
    "sex": "male",
    "date_of_birth": "1999-11-23",
    "city": "San Francisco",
    "account_creation_date": "2023-01-15",
    "email": "[email protected]",
    "last_name": "Smith",
    "first_name": "John"
  },
  "type": "athlete",
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  }
}

Returned upon successful data request

Retrieve activity data for a given user ID

get

Fetches completed workout sessions, with a defined start and end time and activity type (e.g. running, cycling, etc.)

Authorizations

Query parameters

user_idstringrequired

user ID to query data for

start_dateone ofrequired

start date of data to query for - either ISO8601 date or unix timestamp

end_dateone ofoptional

end date of data to query for - either ISO8601 date or unix timestamp

to_webhookbooleanoptional

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

with_samplesbooleanoptional

boolean flag specifying whether to include detailed samples in the returned payload

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/activity?user_id=text&start_date=1' \
  --header 'x-api-key: text' \
  --header 'dev-id: text'

200

400

401

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "data": [
    {
      "active_durations_data": {
        "activity_levels_samples": [
          {
            "activity_level": "MEDIUM_INTENSITY",
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "num_continuous_inactive_periods": 3,
        "inactivity_seconds": 600,
        "vigorous_intensity_seconds": 300,
        "activity_seconds": 1800,
        "low_intensity_seconds": 900,
        "rest_seconds": 120,
        "moderate_intensity_seconds": 600
      },
      "lap_data": {
        "laps": [
          {
            "calories": 50,
            "avg_hr_bpm": 145,
            "start_time": "1999-11-23T09:00:00.000000+02:00",
            "avg_speed_meters_per_second": 3.5,
            "distance_meters": 400,
            "total_strokes": 20,
            "end_time": "2022-10-28T10:00:00.000000+01:00",
            "stroke_type": "FREESTYLE"
          }
        ]
      },
      "cheat_detection": 0,
      "polyline_map_data": {
        "summary_polyline": "}_p~iF~ps|U_ulLnnqC_mqNvxq`@"
      },
      "strain_data": {
        "strain_level": 8.5
      },
      "position_data": {
        "position_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 300,
            "coords_lat_lng_deg": [
              -18.4911,
              130.9123
            ]
          }
        ],
        "end_pos_lat_lng_deg": [
          -84.4911,
          -150.9123
        ],
        "center_pos_lat_lng_deg": [
          -18.4911,
          130.9123
        ],
        "start_pos_lat_lng_deg": [
          80.2394,
          102.931
        ]
      },
      "movement_data": {
        "max_pace_minutes_per_kilometer": 6.5,
        "adjusted_max_speed_meters_per_second": 4.2,
        "avg_velocity_meters_per_second": 3,
        "max_velocity_meters_per_second": 4.5,
        "avg_speed_meters_per_second": 3.2,
        "avg_torque_newton_meters": 40,
        "cadence_samples": [
          {
            "timer_duration_seconds": 300,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "cadence_rpm": 85
          }
        ],
        "max_speed_meters_per_second": 4.5,
        "avg_pace_minutes_per_kilometer": 6.2,
        "avg_cadence_rpm": 85,
        "max_torque_newton_meters": 55.5,
        "torque_samples": [
          {
            "torque_newton_meters": 45.5,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 300
          }
        ],
        "normalized_speed_meters_per_second": 3.8,
        "max_cadence_rpm": 110,
        "speed_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 300,
            "speed_meters_per_second": 3.5
          }
        ]
      },
      "oxygen_data": {
        "vo2max_ml_per_min_per_kg": 42.5,
        "avg_saturation_percentage": 97,
        "vo2_samples": [
          {
            "vo2max_ml_per_min_per_kg": 45.5,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "saturation_samples": [
          {
            "percentage": 98,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "type": 0
          }
        ]
      },
      "device_data": {
        "manufacturer": "Garmin",
        "hardware_version": "v2.1",
        "other_devices": [
          {
            "manufacturer": "Garmin",
            "hardware_version": "v2.1",
            "serial_number": "GR123456789",
            "name": "Forerunner 945",
            "software_version": "5.2.1"
          }
        ],
        "activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
        "serial_number": "GR123456789",
        "name": "Forerunner 945",
        "software_version": "5.2.1"
      },
      "energy_data": {
        "energy_planned_kilojoules": 1200,
        "energy_kilojoules": 1150
      },
      "MET_data": {
        "num_inactive_minutes": 5,
        "MET_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "level": 4.2
          }
        ],
        "num_low_intensity_minutes": 15,
        "num_moderate_intensity_minutes": 25,
        "avg_level": 3.8,
        "num_high_intensity_minutes": 10
      },
      "power_data": {
        "avg_watts": 185,
        "max_watts": 350,
        "power_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 1800,
            "watts": 250
          }
        ]
      },
      "distance_data": {
        "summary": {
          "distance_meters": 5000,
          "elevation": {
            "gain_planned_meters": 500,
            "loss_actual_meters": 450,
            "max_meters": 1200,
            "min_meters": 800,
            "gain_actual_meters": 550,
            "avg_meters": 950
          },
          "steps": 6500,
          "floors_climbed": 10,
          "swimming": {
            "num_laps": 20,
            "num_strokes": 500,
            "pool_length_meters": 25
          }
        },
        "detailed": {
          "elevation_samples": [
            {
              "elev_meters": 925,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 1200
            }
          ],
          "distance_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "distance_meters": 2500,
              "timer_duration_seconds": 900
            }
          ],
          "floors_climbed_samples": [
            {
              "floors_climbed": 5,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 600
            }
          ],
          "step_samples": [
            {
              "steps": 3250,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 900
            }
          ]
        }
      },
      "heart_rate_data": {
        "summary": {
          "resting_hr_bpm": 65,
          "avg_hr_bpm": 145,
          "max_hr_bpm": 180,
          "avg_hrv_sdnn": 45.5,
          "hr_zone_data": [
            {
              "zone": "ZONE_2",
              "start_percentage": 60,
              "end_percentage": 70,
              "duration_seconds": 300,
              "name": "Aerobic"
            }
          ],
          "min_hr_bpm": 85,
          "avg_hrv_rmssd": 35.2,
          "user_max_hr_bpm": 190
        },
        "detailed": {
          "hrv_samples_rmssd": [
            {
              "hrv_rmssd": 42.1,
              "timestamp": "2022-11-23T09:00:00.000000+02:00"
            }
          ],
          "hr_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "bpm": 142
            }
          ],
          "hrv_samples_sdnn": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "hrv_sdnn": 48.3
            }
          ]
        }
      },
      "TSS_data": {
        "TSS_samples": [
          {
            "intensity_factor_planned": 0.85,
            "intensity_factor_actual": 0.82,
            "normalized_power_watts": 225,
            "planned": 85,
            "actual": 82,
            "method": "HeartRate"
          }
        ]
      },
      "calories_data": {
        "BMR_calories": 1800,
        "net_activity_calories": 450,
        "total_burned_calories": 2250,
        "net_intake_calories": 200,
        "calorie_samples": [
          {
            "calories": 450,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 1800
          }
        ]
      },
      "metadata": {
        "state": "California",
        "timestamp_localization": 0,
        "country": "United States",
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "summary_id": "123e4567-e89b-12d3-a456-426614174000",
        "city": "San Francisco",
        "type": "RUNNING",
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "name": "Morning Run",
        "upload_type": "UNKNOWN"
      },
      "work_data": {
        "work_kilojoules": 450.5
      }
    }
  ],
  "type": "text"
}

Returned upon successful data request

Retrieve body metrics for a given user ID

get

Fetches body metrics such as weight, height, body fat percentage etc. for a given user ID

Authorizations

Query parameters

user_idstringrequired

user ID to query data for

start_dateone ofrequired

start date of data to query for - either ISO8601 date or unix timestamp

end_dateone ofoptional

end date of data to query for - either ISO8601 date or unix timestamp

to_webhookbooleanoptional

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

with_samplesbooleanoptional

boolean flag specifying whether to include detailed samples in the returned payload

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/body?user_id=text&start_date=1' \
  --header 'x-api-key: text' \
  --header 'dev-id: text'

200

400

401

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "data": [
    {
      "measurements_data": {
        "measurements": [
          {
            "weight_kg": 75.5,
            "bodyfat_percentage": 18.5,
            "BMI": 22.4,
            "water_percentage": 60.5,
            "measurement_time": "2022-11-23T09:00:00.000000+02:00",
            "lean_mass_g": 61500,
            "estimated_fitness_age": "25",
            "skin_fold_mm": 12.5,
            "height_cm": 178,
            "bone_mass_g": 3200,
            "insulin_units": 10.5,
            "muscle_mass_g": 35000,
            "BMR": 1800,
            "urine_color": "pale yellow",
            "RMR": 2000,
            "insulin_type": "rapid-acting"
          }
        ]
      },
      "ketone_data": {
        "ketone_samples": [
          {
            "ketone_mg_per_dL": 1.5,
            "sample_type": "UNKNOWN",
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ]
      },
      "hydration_data": {
        "hydration_amount_samples": 65.5,
        "day_total_water_consumption_ml": 2500
      },
      "device_data": {
        "manufacturer": "Garmin",
        "hardware_version": "v2.1",
        "other_devices": [
          {
            "manufacturer": "Garmin",
            "hardware_version": "v2.1",
            "serial_number": "GR123456789",
            "name": "Forerunner 945",
            "software_version": "5.2.1"
          }
        ],
        "activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
        "serial_number": "GR123456789",
        "name": "Forerunner 945",
        "software_version": "5.2.1"
      },
      "heart_data": {
        "heart_rate_data": {
          "summary": {
            "resting_hr_bpm": 60,
            "avg_hr_bpm": 75,
            "max_hr_bpm": 180,
            "avg_hrv_sdnn": 45.5,
            "hr_zone_data": [
              {
                "zone": "ZONE_2",
                "start_percentage": 60,
                "end_percentage": 70,
                "duration_seconds": 300,
                "name": "Aerobic"
              }
            ],
            "min_hr_bpm": 45,
            "avg_hrv_rmssd": 42.8,
            "user_max_hr_bpm": 190
          },
          "detailed": {
            "hrv_samples_rmssd": [
              {
                "hrv_rmssd": 42.1,
                "timestamp": "2022-11-23T09:00:00.000000+02:00"
              }
            ],
            "hr_samples": [
              {
                "timestamp": "2022-11-23T09:00:00.000000+02:00",
                "bpm": 142
              }
            ],
            "hrv_samples_sdnn": [
              {
                "timestamp": "2022-11-23T09:00:00.000000+02:00",
                "hrv_sdnn": 48.3
              }
            ]
          }
        },
        "pulse_wave_velocity_samples": [
          {
            "pulse_wave_velocity_meters_per_second": 7.2,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "afib_classification_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "afib_classification": "NORMAL"
          }
        ],
        "ecg_signal": [
          {
            "start_timestamp": "2022-11-23T09:00:00.000000+02:00",
            "avg_hr_bpm": 72.5,
            "afib_classfication": 1,
            "raw_signal": [
              {
                "potential_uV": 1250.5,
                "timestamp": "2022-11-23T09:00:00.000000+02:00"
              }
            ]
          }
        ],
        "rr_interval_samples": [
          {
            "rr_interval_ms": 850,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "hr_bpm": 72
          }
        ]
      },
      "oxygen_data": {
        "vo2max_ml_per_min_per_kg": 42.5,
        "avg_saturation_percentage": 97,
        "vo2_samples": [
          {
            "vo2max_ml_per_min_per_kg": 45.5,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "saturation_samples": [
          {
            "percentage": 98,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "type": 0
          }
        ]
      },
      "glucose_data": {
        "detailed_blood_glucose_samples": [
          {
            "glucose_level_flag": "NORMAL",
            "trend_arrow": "FLAT",
            "blood_glucose_mg_per_dL": 95,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "blood_glucose_samples": [
          {
            "glucose_level_flag": "NORMAL",
            "trend_arrow": "FLAT",
            "blood_glucose_mg_per_dL": 95,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "day_avg_blood_glucose_mg_per_dL": 92.5
      },
      "metadata": {
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "timestamp_localization": 0
      },
      "blood_pressure_data": {
        "blood_pressure_samples": [
          {
            "diastolic_bp": 80.5,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "systolic_bp": 120.5
          }
        ]
      },
      "temperature_data": {
        "body_temperature_samples": [
          {
            "temperature_celsius": 37.2,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "skin_temperature_samples": [
          {
            "temperature_celsius": 37.2,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "ambient_temperature_samples": [
          {
            "temperature_celsius": 37.2,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ]
      }
    }
  ],
  "type": "text"
}

Returned upon successful data request

Retrieve daily activity summaries for a given user ID

get

Fetches daily summaries of activity metrics such as steps, distance, calories burned etc. for a given user ID

Authorizations

Query parameters

user_idstringrequired

user ID to query data for

start_dateone ofrequired

start date of data to query for - either ISO8601 date or unix timestamp

end_dateone ofoptional

end date of data to query for - either ISO8601 date or unix timestamp

to_webhookbooleanoptional

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

with_samplesbooleanoptional

boolean flag specifying whether to include detailed samples in the returned payload

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/daily?user_id=text&start_date=1' \
  --header 'x-api-key: text' \
  --header 'dev-id: text'

200

400

401

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "data": [
    {
      "active_durations_data": {
        "activity_levels_samples": [
          {
            "activity_level": "MEDIUM_INTENSITY",
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "num_continuous_inactive_periods": 3,
        "inactivity_seconds": 28800,
        "vigorous_intensity_seconds": 1800,
        "activity_seconds": 14400,
        "low_intensity_seconds": 7200,
        "rest_seconds": 28800,
        "moderate_intensity_seconds": 5400
      },
      "scores": {
        "sleep": 85,
        "recovery": 78,
        "activity": 92
      },
      "strain_data": {
        "strain_level": 14.5
      },
      "stress_data": {
        "avg_stress_level": 45.5,
        "activity_stress_duration_seconds": 3600,
        "low_stress_duration_seconds": 28800,
        "max_stress_level": 85,
        "medium_stress_duration_seconds": 7200,
        "samples": [
          {
            "steps": 3250,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 900
          }
        ],
        "rest_stress_duration_seconds": 1800,
        "high_stress_duration_seconds": 900,
        "stress_duration_seconds": 5400
      },
      "device_data": {
        "manufacturer": "Garmin",
        "hardware_version": "v2.1",
        "other_devices": [
          {
            "manufacturer": "Garmin",
            "hardware_version": "v2.1",
            "serial_number": "GR123456789",
            "name": "Forerunner 945",
            "software_version": "5.2.1"
          }
        ],
        "activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
        "serial_number": "GR123456789",
        "name": "Forerunner 945",
        "software_version": "5.2.1"
      },
      "tag_data": {
        "tags": [
          {
            "notes": "Felt refreshed after",
            "tag_name": "hot_shower",
            "timestamp": "1999-11-23T09:00:00.000000+02:00"
          }
        ]
      },
      "heart_rate_data": {
        "summary": {
          "resting_hr_bpm": 60,
          "avg_hr_bpm": 75,
          "max_hr_bpm": 180,
          "avg_hrv_sdnn": 45.5,
          "hr_zone_data": [
            {
              "zone": "ZONE_2",
              "start_percentage": 60,
              "end_percentage": 70,
              "duration_seconds": 300,
              "name": "Aerobic"
            }
          ],
          "min_hr_bpm": 45,
          "avg_hrv_rmssd": 42.8,
          "user_max_hr_bpm": 190
        },
        "detailed": {
          "hrv_samples_rmssd": [
            {
              "hrv_rmssd": 42.1,
              "timestamp": "2022-11-23T09:00:00.000000+02:00"
            }
          ],
          "hr_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "bpm": 142
            }
          ],
          "hrv_samples_sdnn": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "hrv_sdnn": 48.3
            }
          ]
        }
      },
      "MET_data": {
        "num_inactive_minutes": 480,
        "MET_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "level": 4.2
          }
        ],
        "num_low_intensity_minutes": 720,
        "num_moderate_intensity_minutes": 180,
        "avg_level": 1.8,
        "num_high_intensity_minutes": 60
      },
      "distance_data": {
        "detailed": {
          "elevation_samples": [
            {
              "elev_meters": 925,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 1200
            }
          ],
          "distance_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "distance_meters": 2500,
              "timer_duration_seconds": 900
            }
          ],
          "floors_climbed_samples": [
            {
              "floors_climbed": 5,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 600
            }
          ],
          "step_samples": [
            {
              "steps": 3250,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 900
            }
          ]
        },
        "distance_meters": 8500,
        "elevation": {
          "gain_planned_meters": 150,
          "loss_actual_meters": 120,
          "max_meters": 450,
          "min_meters": 300,
          "gain_actual_meters": 130,
          "avg_meters": 375
        },
        "steps": 12000,
        "floors_climbed": 15,
        "swimming": {
          "num_laps": 20,
          "num_strokes": 500,
          "pool_length_meters": 25
        }
      },
      "oxygen_data": {
        "vo2max_ml_per_min_per_kg": 45.5,
        "avg_saturation_percentage": 98,
        "vo2_samples": [
          {
            "vo2max_ml_per_min_per_kg": 45.5,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "saturation_samples": [
          {
            "percentage": 98,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "type": 0
          }
        ]
      },
      "calories_data": {
        "BMR_calories": 1800,
        "net_activity_calories": 500,
        "total_burned_calories": 2300,
        "net_intake_calories": 2000,
        "calorie_samples": [
          {
            "calories": 450,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 1800
          }
        ]
      },
      "metadata": {
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "upload_type": "UNKNOWN",
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "timestamp_localization": 0
      }
    }
  ],
  "type": "text"
}

Returned upon successful data request

Retrieve menstruation data for a given user ID

get

Fetches menstruation data such as cycle length, period length, ovulation date etc. for a given user ID

Authorizations

Query parameters

user_idstringrequired

user ID to query data for

start_dateone ofrequired

start date of data to query for - either ISO8601 date or unix timestamp

end_dateone ofoptional

end date of data to query for - either ISO8601 date or unix timestamp

to_webhookbooleanoptional

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

with_samplesbooleanoptional

boolean flag specifying whether to include detailed samples in the returned payload

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/menstruation?user_id=text&start_date=1' \
  --header 'x-api-key: text' \
  --header 'dev-id: text'

200

400

401

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "data": [
    {
      "metadata": {
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "timestamp_localization": 0
      },
      "menstruation_data": {
        "length_of_current_phase_days": 5,
        "period_length_days": 5,
        "cycle_length_days": "28",
        "days_until_next_phase": 23,
        "is_predicted_cycle": "true",
        "last_updated_time": "2022-12-12T14:03:05.000000-05:00",
        "current_phase": 1,
        "period_start_date": "2022-11-28",
        "predicted_cycle_length_days": 28,
        "menstruation_flow": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "flow": "UNKNOWN"
          }
        ],
        "day_in_cycle": 24
      }
    }
  ],
  "type": "text"
}

Returned upon successful data request

Retrieve nutrition log data for a given user ID

get

Fetches nutrition log data such as meal type, calories, macronutrients etc. for a given user ID

Authorizations

Query parameters

user_idstringrequired

user ID to query data for

start_dateone ofrequired

start date of data to query for - either ISO8601 date or unix timestamp

end_dateone ofoptional

end date of data to query for - either ISO8601 date or unix timestamp

to_webhookbooleanoptional

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

with_samplesbooleanoptional

boolean flag specifying whether to include detailed samples in the returned payload

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/nutrition?user_id=text&start_date=1' \
  --header 'x-api-key: text' \
  --header 'dev-id: text'

200

400

401

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "data": [
    {
      "summary": {
        "micros": {
          "iron_mg": 8.5,
          "magnesium_mg": 320,
          "vitamin_A_mg": 0.9,
          "vitamin_B12_mg": 0.0024,
          "biotin_mg": 0.03,
          "cystine_g": 0.3,
          "phenylalanine_g": 0.9,
          "chloride_mg": 2300,
          "vitamin_D3_mg": 0.015,
          "isoleucine_g": 0.8,
          "calcium_mg": 1000,
          "iodine_mg": 0.15,
          "histidine_g": 0.6,
          "chromium_mg": 0.035,
          "vitamin_K_mg": 0.12,
          "manganese_mg": 2.3,
          "folic_acid_mg": 0.4,
          "leucine_g": 1.2,
          "caffeine_mg": 95,
          "potassium_mg": 3500,
          "molybdenum_mg": 0.045,
          "lysine_g": 0.9,
          "tyrosine_g": 0.7,
          "valine_g": 0.8,
          "omega6_g": 17,
          "omega3_g": 1.6,
          "vitamin_C_mg": 90,
          "zinc_mg": 11,
          "vitamin_D2_mg": 0.01,
          "vitamin_E_mg": 15,
          "pantothenic_acid_mg": 5,
          "riboflavin_mg": 1.3,
          "phosphorus_mg": 1000,
          "vitamin_D_mg": 0.02,
          "tryptophan_g": 0.3,
          "niacin_mg": 16,
          "copper_mg": 0.9,
          "threonine_g": 0.5,
          "monounsaturated_fat_g": 15,
          "folate_mg": 0.4,
          "selenium_mg": 0.055,
          "vitamin_B6_mg": 1.7,
          "thiamin_mg": 1.2,
          "polyunsaturated_fat_g": 13,
          "methionine_g": 0.6,
          "starch_g": 25
        },
        "macros": {
          "fiber_g": 25,
          "calories": 2000,
          "fat_g": 65,
          "sodium_mg": 2300,
          "alcohol_g": 14,
          "trans_fat_g": 2,
          "carbohydrates_g": 300,
          "protein_g": 50,
          "saturated_fat_g": 20,
          "sugar_g": 25,
          "cholesterol_mg": 300,
          "net_carbohydrates_g": 275
        },
        "water_ml": 2000
      },
      "drink_samples": [
        {
          "drink_unit": "ml",
          "timestamp": "2022-11-23T09:00:00.000000+02:00",
          "drink_name": "Water",
          "drink_volume": "250"
        }
      ],
      "metadata": {
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "timestamp_localization": 0
      },
      "meals": [
        {
          "micros": {
            "iron_mg": 8.5,
            "magnesium_mg": 320,
            "vitamin_A_mg": 0.9,
            "vitamin_B12_mg": 0.0024,
            "biotin_mg": 0.03,
            "cystine_g": 0.3,
            "phenylalanine_g": 0.9,
            "chloride_mg": 2300,
            "vitamin_D3_mg": 0.015,
            "isoleucine_g": 0.8,
            "calcium_mg": 1000,
            "iodine_mg": 0.15,
            "histidine_g": 0.6,
            "chromium_mg": 0.035,
            "vitamin_K_mg": 0.12,
            "manganese_mg": 2.3,
            "folic_acid_mg": 0.4,
            "leucine_g": 1.2,
            "caffeine_mg": 95,
            "potassium_mg": 3500,
            "molybdenum_mg": 0.045,
            "lysine_g": 0.9,
            "tyrosine_g": 0.7,
            "valine_g": 0.8,
            "omega6_g": 17,
            "omega3_g": 1.6,
            "vitamin_C_mg": 90,
            "zinc_mg": 11,
            "vitamin_D2_mg": 0.01,
            "vitamin_E_mg": 15,
            "pantothenic_acid_mg": 5,
            "riboflavin_mg": 1.3,
            "phosphorus_mg": 1000,
            "vitamin_D_mg": 0.02,
            "tryptophan_g": 0.3,
            "niacin_mg": 16,
            "copper_mg": 0.9,
            "threonine_g": 0.5,
            "monounsaturated_fat_g": 15,
            "folate_mg": 0.4,
            "selenium_mg": 0.055,
            "vitamin_B6_mg": 1.7,
            "thiamin_mg": 1.2,
            "polyunsaturated_fat_g": 13,
            "methionine_g": 0.6,
            "starch_g": 25
          },
          "type": "BREAKFAST",
          "id": "food_123",
          "timestamp": "2022-12-12T08:53:00.000000+02:00",
          "quantity": {
            "unit": "grams",
            "amount": 100
          },
          "name": "Oatmeal",
          "macros": {
            "fiber_g": 25,
            "calories": 2000,
            "fat_g": 65,
            "sodium_mg": 2300,
            "alcohol_g": 14,
            "trans_fat_g": 2,
            "carbohydrates_g": 300,
            "protein_g": 50,
            "saturated_fat_g": 20,
            "sugar_g": 25,
            "cholesterol_mg": 300,
            "net_carbohydrates_g": 275
          }
        }
      ]
    }
  ],
  "type": "text"
}

Returned upon successful data request

REST API Endpoints

REST API Endpoints

🕸️ API info

🔌 Authentication

💁‍♂️ User info

⏳ Historical Data retrieval

✏️ Writing data

🕸️ API info

🔌 Authentication

💁‍♂️ User info

⏳ Historical Data retrieval

✏️ Writing data

Get list of available integrations

Get detailed list of integrations

Deauthenticates a user and deletes any cached data for them

Retrieve user profile info for a given user ID

Retrieve activity data for a given user ID

Retrieve body metrics for a given user ID

Retrieve daily activity summaries for a given user ID

Retrieve menstruation data for a given user ID

Retrieve nutrition log data for a given user ID

Retrieve sleep sessions for a given user ID

🕸️ API info

🔌 Authentication

💁‍♂️ User info

⏳ Historical Data retrieval

✏️ Writing data

🕸️ API info

🔌 Authentication

💁‍♂️ User info

⏳ Historical Data retrieval

✏️ Writing data

Get list of available integrations

Get detailed list of integrations

Deauthenticates a user and deletes any cached data for them

Retrieve user profile info for a given user ID

Retrieve activity data for a given user ID

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Retrieve body metrics for a given user ID

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Retrieve daily activity summaries for a given user ID

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Retrieve menstruation data for a given user ID

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Retrieve nutrition log data for a given user ID

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Retrieve sleep sessions for a given user ID