terra-models

Terra API モデル

接続済みユーザーのデータに対して、Terra API のヘルスモデルを指定した期間で実行し、すぐに使えるインサイトを取得できます。1 回のリクエストで、1 つのインサイトが返ります。モデルをホストする必要はありません。各モデルが示すのはウェルネス指標であり、医療ツールや診断ツールではありません。出力を臨床的なものとして提示しないでください。

アカウントツール：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

このログについて、知っておくべきことが 2 つあります。デフォルトでは30 日分が保存されるため、それより古い実行はログに表示されず、ページが空でも実行がなかった証拠にはなりません。ただし、--run-id を指定すると、保存されている全履歴を対象に検索するため、ID がわかっている実行が期間の制限で除外されることはありません。

インサイトが返るかどうかにかかわらず、実行にはクレジットが必要です。そのため、runs list --status error を使えば、何も生成されなかった実行にクレジットが消費されているかを最も手早く確認できます。

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 admin MCP サーバーを使用してください。サンドボックスでは CLI をインストールしたり、サインインしたりできないためです。各管理コマンドは、その名前と method で表されるツールです（terra users list は method: "list" を指定した users_read です）。terra data-api、terra admin-api、terra examples を利用できるのは CLI のみです。また、--select と --jq に相当する MCP の機能はありません。terra-cli と terra-mcp のスキルには、変更の確認や認証情報をトランスクリプトに残さないことなどの安全策、エラー、タスク別の手順が記載されています。これらは連携を管理するためのものであり、このスキルで説明する API 呼び出しの代わりにはなりません。

このスキルの用途

GET /v2/models または GET /v2/models/run を呼び出すもの、model_run の利用料金を計算するもの、あるいはユーザーの Terra API データを睡眠スケジュール、月経周期、または欠損値を補完した指標のインサイトに変換するものを構築する場合に使用します。

まずユーザーを接続する

Models は、Unified API を通じて接続したユーザー（terra-unified-api スキルを参照）のデータに対して、指定した期間で実行します。指定したユーザーと期間でインサイトを返せない場合もあります。その場合は、未対応の結果またはエラーが返されますが、どちらの場合も実行にはクレジットが必要です（「結果の読み方」と「料金」を参照）。

3 つのモデル（一般提供）

model ID	返される内容	必要なデータ
sleep_window	推奨される就寝時刻、起床時刻、ベッドにいる時間、バンド付きの 0～100 の一貫性スコア、およびスコアを最も改善する単一の変更点	ユーザーの過去の記録全体から取得した夜間の睡眠セッション
cycle_phase_tracker	日ごとの月経周期のフェーズに加え、夜間の生理データから検出された月経開始日と妊娠可能期間。それぞれに信頼度のバンドが付きます	心拍数と HRV を含む、少なくとも 30 日分の夜間の睡眠データ
graph_impute	スマート入力：選択したテーブルの 1 日分の指標。デバイスが記録したものとモデルが再構成したものが示されます	指定したテーブルにおける、そのユーザーの記録済み履歴

sleep_window、cycle_phase_tracker、graph_impute は一般提供（GA）されており、ドキュメントが用意されています。それ以外のモデル ID は GA 前で不安定なものとして扱ってください。実行できる場合もありますが、予告なく応答の形式が変わる可能性があります。

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 には追加のパラメーターが 1 つ必要です。table に sleeps、dailies、activities のいずれかを指定します。 このエンドポイントは、テーブルを自動選択せず、指定がない場合は実行を拒否するため、汎用パラメーター一覧だけを使って構築したリクエストは 400 を返します。3 つのテーブルには、それぞれ異なる指標が含まれます。

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 ケースではありません。無視しないでください。
• 失敗を含め、すべての実行で課金されます。 実行は計算前に使用量として計上されるため、未対応またはエラーになった実行でもクレジットを消費します。手当たり次第に試すのではなく、事前にモデル 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 は、回答のリストではありません。 指定した期間の暦日ごとに 1 行が含まれ、モデルにデータがなかった日も含まれます。そのため、results.length がデータの網羅性を示すことはありません。各行の available に基づいて分岐してください。生の確率値ではなく、*_confidence の区分（low／medium／high）を参照してください。また、月経日は妊娠可能日と重複しません。
• graph_impute では computed と reported が重要です。 1 日分の fields に含まれる各エントリーには、デバイスが実際に値を記録した場合は reported: true、モデルが値を再構成した場合は computed: true が含まれます。再構成された値には confidence も含まれます。計算値を記録値として提示しないでください。
• レスポンスの data_type は、カタログの data_type と同じではありません。 カタログにはモデルが読み取るデータが記載されています（sleep_window → sleep）。実行レスポンスにはモデル独自の値が記載されています（sleep_window → sleep_window）。一方から他方を決めつけないでください。
• truncated: true は、実行がリクエストごとのデータ上限に達したことを意味します。インサイトは引き続き有効ですが、指定範囲のうち上限内のデータに基づいて計算されています。
• モデルの出力は、確度が控えめな指標です。単一の結果を確定的なものとして提示しないでください。

料金

従量制：モデルの実行 1 回につき $0.01 で、プランの月間クレジット枠から差し引かれます。1 回の実行とは、期間に含まれるデータ量にかかわらず、1 人のユーザーに対して 1 つのモデルを 1 つの日付範囲で実行することです。2 つのモデルを実行する場合、または同じモデルを 2 人のユーザーに対して実行する場合は、2 回の実行となります。Terra API ダッシュボードから開始した実行も、この API を通じて実行した場合も、同じ方法で課金されます。詳細：https://docs.tryterra.co/unified-api/pricing

境界

• Unified API ではありません。 ユーザー、Webhook、履歴データの接続には Unified API（terra-unified-api）を使用します。モデルの実行では、接続済みのユーザーのデータを分析し、インサイトを返します。
• Health Scores ではありません。 Health Scores は継続的な生理学的スコアです。Models は単一の呼び出しから、オンデマンドで離散的なインサイトを返します。