> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/models/models.md).

# Overview

## 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**.

{% hint style="success" %}

### Prerequisites

1. **API Key & dev-id** — obtain both from your [Terra Dashboard](https://dashboard.tryterra.co/).
2. **A connected user** — models run over a connected user's data, so you need at least one connected `user_id`.
   {% endhint %}

***

## 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.

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

```json
{
  "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).         |

```bash
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:

```json
{
  "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:

```json
{
  "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.

{% hint style="warning" %}

### 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.
{% endhint %}

***

## 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](/unified-api/pricing.md). A run over one user for one date range is one credit, regardless of how much data it covers.