terra-models

Terra API 模型

针对已连接用户的数据，在指定日期范围内运行 Terra API 的一项健康模型，即可获得可直接使用的洞察：一次请求，返回一条洞察。无需托管模型。每个模型都是健康指标，而非医疗或诊断工具；切勿将其输出描述为临床结果。

账户工具：CLI 或 MCP

Models 有自己的账户命令，其中包括运行日志，可查看运行结果为何与预期不符：

terra models catalog list                                           # the models available, account-wide
terra models runs list --env <dev-id> --status error                # failed runs
terra models runs list --env <dev-id> --user-id <uuid> --model <model>
terra models runs list --env <dev-id> --run-id <run_id>             # one run, by id

关于该日志，有两点需要注意。默认情况下，日志保留 30 天，因此较早的运行记录不会出现在其中；页面为空也不能证明运行从未发生。不过，--run-id 会将查询范围扩展到所有保留的历史记录，因此只要你有运行 ID，就不会受时间窗口限制。

无论是否返回洞察，每次运行都会消耗一个点数。因此，runs list --status error 也是最快的方式，可查看有多少点数花在了未产生任何结果的运行上。

在编码 Agent（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 或登录。每个管理命令的工具名称和 method 都对应其命令（terra users list 对应 users_read，且 method: "list"）。只有 CLI 支持 terra data-api、terra admin-api 和 terra examples；--select 和 --jq 也没有对应的 MCP 功能。terra-cli 和 terra-mcp 技能包含相关防护措施（确认更改、防止凭据出现在对话记录中）、错误说明，以及按任务分类的操作指南。这些工具用于管理集成，不会替代本技能介绍的 API 调用。

适用场景

构建调用 GET /v2/models 或 GET /v2/models/run、为 model_run 用量定价，或将用户的 Terra API 数据转化为睡眠时间表、月经周期或补全缺失指标洞察的功能。

先连接用户

模型会针对你通过 Unified API 连接的用户运行（参见 terra-unified-api 技能），并使用你选择的日期范围。对于特定用户和日期范围，模型不一定总能返回洞察；无法返回时，你会得到不支持结果或错误，而无论哪种情况，本次运行仍会消耗一个点数（参见“读取结果”和“定价”）。

三种模型（普遍可用）

model id	返回内容	所需数据
sleep_window	建议的就寝时间、起床时间和卧床时长；0–100 的规律性评分及其等级；以及最能改善该评分的一项调整	用户历史记录中的跨夜睡眠时段
cycle_phase_tracker	每日月经周期阶段，以及从跨夜生理数据中检测到的月经开始时间和易孕期，并为每项提供置信度等级	至少 30 天包含心率和 HRV 的跨夜睡眠数据
graph_impute	智能填充：所选表格中某一天的指标，并标明哪些由设备记录、哪些由模型重建	该用户在你所选表格中的已记录历史

sleep_window、cycle_phase_tracker 和 graph_impute 均已正式发布（GA），并有文档说明。请将任何其他模型 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 格式。

读取结果（Agent 最容易出错的部分）

• 不支持的设备会返回 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 情况不同；不要忽略这类错误。
• 每次运行都会计费，包括失败的运行。 运行会在计算前计量，因此不支持或出错的运行仍会消耗一个额度。请预先验证模型 ID、用户和设备是否受支持，不要盲目尝试。
• 结果为空并不总是 unsupported。 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，band 为 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；重建的值还会带有 confidence。切勿将计算出的值呈现为设备记录的值。
• 响应中的 data_type 与目录中的 data_type 不同。 目录报告的是模型读取的数据（sleep_window → sleep）；运行响应报告的是自身的值（sleep_window → sleep_window）。不要根据其中一个来断言另一个。
• truncated: true 表示运行触及了每次请求的数据上限；洞察仍然有效，但只根据该范围内有限的一部分数据计算得出。
• 模型输出只是可信度有限的指标。不要将单个结果视为权威结论。

定价

按使用量计费：每次模型运行 $0.01，从套餐的月度额度中扣除。一次运行是针对一个用户、一个日期范围运行一个模型，无论该范围包含多少数据；运行两个模型，或对两个用户运行同一个模型，都算两次运行。从 Terra API 仪表板发起的运行和通过此 API 发起的运行，计费路径完全相同。详情：https://docs.tryterra.co/unified-api/pricing

边界

• 不是 Unified API。 连接用户、Webhook 和历史数据属于 Unified API（terra-unified-api）；模型运行会分析已连接用户的数据并返回一条洞察。
• 不是 Health Scores。 Health Scores 是持续的生理评分；模型通过单次调用按需返回一条离散的洞察。