Overview
Run Terra's health models over your users' data to turn raw metrics into ready-to-use wellness insights.
Models run Terra's health models over a user's data and return ready-to-use insights, with 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.
Available models
Three 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.
Menstrual Cycle Tracker
cycle_phase_tracker
A per-day cycle phase, plus the period onsets and fertile windows detected in a user's overnight physiology. No logged period dates are needed or read.
Smart Fill
graph_impute
Reconstructs the metrics a user's device did not record for a day, alongside the ones it did, with a confidence on each reconstructed value.
List available models
Returns the models you can run.
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
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).
table
query
Smart Fill only, and required for it: which table to reconstruct: sleeps, dailies or activities. The three carry different metrics, so the model will not pick one for you.
Sleep Window returns a recommended schedule and how consistent the user already is:
approximate is true when the schedule is estimated from limited history. sleep_regularity.score is a 0–100 index with a band of Low / Fair / Good / Excellent. recommendation names the single change that would raise the score most, and is absent when the user is already consistent.
Sleep Window reads the user's whole history rather than the range you pass, so start_time and end_time do not change its answer.
Menstrual Cycle Tracker returns one row per calendar day of the range, plus the cycles it detected:
results holds one row per day in the range including days the model had no data for, so check available rather than assuming every row is an answer. period and fertile say what was detected; the matching *_confidence is a band of low / medium / high. Read the bands, not raw probabilities. A period day is never also a fertile day.
temperature_used tells you which variant ran. Skin temperature makes the reading materially more precise, and the model only uses it where it can be placed in the feature space it was trained on: natively for Oura, through its device mapping for Fitbit. Every other device is scored by a dedicated temperature-free variant even when it reports a temperature of its own.
The tracker needs at least 30 days of overnight history with heart rate and HRV. It is a wellness indicator, not a medical or contraceptive tool.
Smart Fill returns the day's metrics, marking which were reconstructed:
computed: true marks a value the model reconstructed and reported: true a value the device actually recorded, so you can always tell them apart. A reconstructed value carries a confidence. Smart Fill needs a table (see above) and returns recorded values alongside reconstructed ones, so a scoped token needs data:read as well as models:run; a plain API key is unaffected.
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.
Last updated
Was this helpful?