Overview

Run Terra's health models over your users' data to turn raw metrics into ready-to-use wellness insights.

Overview

Models run Terra's health models over a user's data and return ready-to-use insights — no extra data collection, no model to host yourself. You call one endpoint with a user_id and a date range, and Terra returns the result.

Every model is a wellness indicator, not a medical or diagnostic tool.

You can run models two ways, and they behave identically:

• From the API — call the endpoint below with your API key. This is the same request the dashboard makes.

• From the Terra Dashboard — open Models, pick a model and a user, and click Run.

Prerequisites

1. API Key & dev-id — obtain both from your Terra Dashboard.

2. A connected user — models run over a connected user's data, so you need at least one connected user_id.

---

Available models

Two models are generally available today; more are in active development.

Model	model id	What it returns
Sleep Window	sleep_window	A steady, personalised sleep schedule (recommended bed and wake times) to help keep a user's sleep timing consistent. More regular sleep timing is associated with better recovery and sleep quality.
Health Terrain	health_terrain	How a user's body shifted over the last week across 15 broad health areas, relative to their own recent baseline — a glanceable surface of what flared up and what stayed flat.

---

List available models

Returns the models you can run.

curl --request GET 'https://api.tryterra.co/v2/models' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'dev-id: YOUR_DEV_ID'

{
  "status": "success",
  "models": [
    { "id": "sleep_window", "name": "Sleep Window", "description": "…", "data_type": "sleep" },
    { "id": "health_terrain", "name": "Health Terrain", "description": "…", "data_type": "daily" }
  ]
}

---

Run a model

Runs the chosen model over one user's data for a date range and returns its result. It is read-only and does not trigger a new data pull from the provider.

GET https://api.tryterra.co/v2/models/run

Parameter	In	Description
x-api-key	header	Your Terra API key.
dev-id	header	Your developer id.
model	query	The model id, e.g. sleep_window.
user_id	query	The Terra user to run the model over.
start_time	query	Start of the window (ISO 8601).
end_time	query	End of the window (ISO 8601).

curl --request GET \
  'https://api.tryterra.co/v2/models/run?model=sleep_window&user_id=USER_ID&start_time=2026-04-01T00:00:00Z&end_time=2026-07-01T00:00:00Z' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'dev-id: YOUR_DEV_ID'

Sleep Window returns a recommended schedule:

{
  "status": "success",
  "model": "sleep_window",
  "user_id": "USER_ID",
  "window": {
    "recommended_bed": "23:04",
    "recommended_wake": "07:06",
    "in_bed_h": 8.0,
    "approximate": false
  }
}

approximate is true when the schedule is estimated from limited history.

Health Terrain returns one entry per health area:

{
  "status": "success",
  "model": "health_terrain",
  "user_id": "USER_ID",
  "areas": [
    {
      "name": "Sleep Trouble",
      "explainer": "This body looked like it slept more soundly than usual.",
      "sigma": -1.07,
      "week_activation": 0.02
    }
  ]
}

sigma is the week's shift for that area relative to the user's own baseline (negative = below baseline, positive = above). Each area also carries x/y layout coordinates you can use to plot the areas as a map.

Supported devices & data

Each model needs the right kind of data. If a user's device isn't supported, or there isn't enough history yet, the response returns unsupported: true (with an unsupported_reason and the list of supported devices) or an empty result rather than an error — so you can message the user accordingly.

---

Pricing

Model runs are usage-based: 1 credit per run, and each credit costs $0.01, drawn from your plan's monthly credit allowance — see Pricing. A run over one user for one date range is one credit, regardless of how much data it covers.