Terra API Models 用于针对已连接用户的指定日期范围数据运行 Terra API 健康模型，返回可直接使用的洞察：一次请求输入，一个洞察输出，无需自行托管模型。每个模型都是健康指标，而非医疗或诊断工具，绝不能将其输出作为临床结论呈现。
账户工具：CLI 或 MCP
Models 拥有自己的账户命令，包括可说明某次运行为何未返回预期结果的运行日志：
terra models catalog list # 账户范围内可用的模型
terra models runs list --env <dev-id> --status error # 失败运行
terra models runs list --env <dev-id> --user-id <uuid> --model <model>
terra models runs list --env <dev-id> --run-id <run_id> # 按 id 查单次运行
关于该日志有两点。默认保留 30 天，因此更早的运行不在其中，空页面并不能证明某次运行从未发生。但 --run-id 会将查找范围扩展到完整保留历史，因此只要你持有某次运行的 id，它就不会被时间窗口截断。
由于一次运行无论是否返回洞察都会消耗一个 credit，runs list --status error 也是查看 credit 被花费在从未产出任何结果的运行上的最快方式。
在编码智能体（Claude Code、Codex、Cursor 等，运行在用户机器上或云端）中使用 CLI，若缺失可提议安装：macOS 和 Linux 使用 curl -fsSL https://cli.tryterra.co/install.sh | sh，Windows PowerShell 使用 irm "https://cli.tryterra.co/install.ps1" | iex，或在用户已使用的情况下通过 Homebrew 或 npm 安装。在聊天助手（claude.ai、Claude Desktop、ChatGPT）中使用 Terra API 管理端 MCP 服务器，即便它能运行代码：其沙箱无法安装 CLI 或登录。每条管理命令都是一个工具，其名称与方法直接对应（terra users list 即 users_read，method: "list"）。只有 CLI 拥有 terra data-api、terra admin-api 和 terra examples，且 --select 与 --jq 没有 MCP 等价物。terra-cli 和 terra-mcp 技能承载了防护规则（确认变更、避免凭据进入对话记录）、错误处理及每类任务的 playbook。它们负责管理集成，并不替代本技能所描述的 API 调用。
何时使用
构建任何调用 GET /v2/models 或 GET /v2/models/run、对 model_run 用量计价，或将用户的 Terra API 数据转化为睡眠计划、月经周期或缺口填充指标洞察的应用时适用。
先连接用户
模型针对已通过 Unified API 连接的用户运行（参见 terra-unified-api 技能），日期范围由你选择。模型并非总能对给定用户和范围返回洞察；无法返回时会得到 unsupported 结果或错误，且无论哪种情况该次运行仍消耗一个 credit（参见结果解读与定价）。
三个模型（正式可用）
| model id | 返回 | 需要 |
|---|---|---|
| sleep_window | 建议的就寝时间、起床时间和卧床时长，0–100 的一致性评分及分档，以及最能改善它的一项改变 | 用户历史中的过夜睡眠会话 |
| cycle_phase_tracker | 逐日月经周期阶段，以及从过夜生理数据检测到的经期开始与易孕窗口，各带置信区间 | 至少 30 天带心率和 HRV 的过夜睡眠 |
| graph_impute | Smart Fill：所选表某一天的指标，标明哪些由设备记录、哪些由模型重建 | 该用户在所请求表中的记录历史 |
sleep_window、cycle_phase_tracker 和 graph_impute 为正式可用并有文档。其他任何 model id 均应视为预发布且不稳定：可能可运行，但响应结构可能在不通知的情况下变化。
cycle_phase_tracker 是健康指标，而非医疗或避孕工具，它仅从生理数据检测经期开始，既不读取也不需要用户记录的经期日期。
发起运行
GET https://api.tryterra.co/v2/models/run
查询参数：model、user_id、start_time、end_time（均为 ISO 8601）。请求头：x-api-key 和 dev-id（你自己的密钥；这不是特权端点）。
graph_impute 还需一个参数：table，取 sleeps、dailies 或 activities 之一。缺少该参数时端点会拒绝运行，而不是替你选择表，因此仅凭通用参数列表构建的请求会返回 400。三张表携带不同的指标。
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'
在构建请求或响应类型之前，先获取 https://docs.tryterra.co/models/models.md 以了解确切参数和每个模型的完整响应结构；响应结构因模型而异且会演进。在获取页面前先向 terra docs ask（或 MCP 上的 docs_ask）提问：它基于文档回答并引用来源。在任何文档 URL 后追加 .md 可获得 markdown。
解读结果（智能体常出错的部分）
不支持的设备是 200，而非错误。当用户的设备或提供商无法产出该模型时，运行返回 HTTP 200 并带 unsupported: true（外加 unsupported_reason 和 supported/supported_devices），替代洞察。应将其作为正常结果处理并呈现给用户，而非失败。
真正的错误是真正的错误。错误或缺失的输入返回 4xx，无法计算的运行（例如范围内数据过少）可返回 5xx。这些以 RFC 7807 problem+json 返回（title、detail，验证错误在 errors[]），例如 400 unknown model、404 invalid user id。这不是上述优雅的 unsupported 情形，不要吞掉它。
每次运行都计费，包括失败。运行在计算前即被计量，因此 unsupported 或出错的运行仍消耗一个 credit。应预先验证 model id、用户及设备是否受支持，而不是盲目试探。
空不等于总是不支持。sleep_window 对无法服务的设备使用 unsupported/unsupported_reason，对历史过少的用户使用 no_data/no_data_reason。cycle_phase_tracker 只使用 no_data/no_data_reason。两种键都要处理，不要只对 unsupported 分支。
响应结构因模型而异。sleep_window 返回 window 对象（recommended_bed/recommended_wake 为本地时钟时间；approximate: true 表示排程基于有限历史估算）、sleep_regularity 对象（score 0–100 及 Low/Fair/Good/Excellent 分档），以及（除非用户已足够规律）recommendation 对象（change、reason、moves_to、gain），指出最能提升评分的单项改变。cycle_phase_tracker 返回 results 以及 periods 和 fertile_windows。graph_impute 返回 table、features 和 results。
sleep_window 忽略你传入的范围。它读取用户的全部睡眠历史，因此 start_time 和 end_time 不改变其结果。不要构建暗示选择窗口会改变排程的 UI。
cycle_phase_tracker 的 results 不是答案列表。它对你所请求范围内的每个日历日各带一行，包括模型无数据的日期——因此 results.length 从不是覆盖率信号。应基于每行的 available 分支。读取 *_confidence 分档（low/medium/high），而非原始概率，并注意经期日绝不会同时是易孕日。
对 graph_impute 而言，computed 与 reported 是关键。某日 fields 中每个条目在设备实际记录该值时带 reported: true，在模型重建时带 computed: true，重建值附有置信度。绝不能将 computed 值呈现为已记录。
响应的 data_type 与目录的 data_type 不同。目录报告模型读取的数据（sleep_window → sleep）；运行响应报告其自身的值（sleep_window → sleep_window）。不要由其一推断另一。
truncated: true 表示运行触及了每请求数据上限；洞察仍有效，但基于范围内有界切片计算。
模型输出是中等置信度的指标。不要将单个结果呈现为权威。
定价
按用量计费：每次模型运行 $0.01，从你计划的每月 credit 额度中扣除。一次运行等于一个模型对一个用户的一个日期范围，无论该范围覆盖多少数据；运行两个模型，或同一模型用于两个用户，即为两次运行。从 Terra API 仪表盘发起的运行与通过此 API 发起的运行按相同路径计费。详情：https://docs.tryterra.co/unified-api/pricing
边界
不是 Unified API。连接用户、webhooks 和历史数据属于 Unified API（terra-unified-api）；模型运行分析已连接用户的数据并返回洞察。
不是 Health Scores。Health Scores 是连续的生理评分；Models 通过单次调用返回离散的按需洞察。