最初のリクエストを送る

iPhoneのteloアプリで、「アカウント」→「プラン」からProに登録し、履歴を同期します。
Webダッシュボードで「アカウント」を開き、プロジェクト用のキーを作成します。すぐに保存してください。シークレット全体が表示されるのは一度だけです。
サーバの環境変数かローカルのシェルにTELO_API_KEYを設定し、下のリクエストを実行します。

curl --fail-with-body 'https://telo.health/api/v1/list_metrics' \
  -H "Authorization: Bearer $TELO_API_KEY"

認証

すべてのリクエストでAuthorization: Bearer <key>を送信してください。各キーが読み取れるのは、そのキーのアカウントだけです。キーはサーバかローカルのマシンに保存し、ブラウザのコード、公開リポジトリ、URLには絶対に含めないでください。CookieやiPhoneのトークンでは、このAPIの認証はできません。

キーは5つまで作成でき、プロジェクトごとに「アカウント」から個別に取り消せます。Proの期限が切れたあとも、取り消しは引き続き行えます。ファウンダーアカウントでも、有料のPro利用権が必要です。返金やサブスクリプションの変更は、既存の課金キャッシュ（最大15分、Webhookで無効化）に従って反映されます。

APIキーを管理

エンドポイント

ベースURL: https://telo.health/api/v1。すべてのエンドポイントはGETを使い、対応するMCPの読み取りツールと同じJSONペイロードを、MCPのエンベロープなしで返します。日付はYYYY-MM-DD形式です。リストはカンマ区切り、真偽値はtrueかfalseです。不明なパラメータや重複したパラメータは拒否されます。

`GET /data_status`

記録の欠けを解釈する前に、カバー範囲、取り込みの進捗、最後の同期を確認します。

必須: なし
任意: なし

curl --fail-with-body 'https://telo.health/api/v1/data_status' \
  -H "Authorization: Bearer $TELO_API_KEY"

`GET /list_metrics`

アカウントで利用できる指標の名前、単位、日付範囲を確認します。

必須: なし
任意: なし

curl --fail-with-body 'https://telo.health/api/v1/list_metrics' \
  -H "Authorization: Bearer $TELO_API_KEY"

`GET /query_daily`

日別の値を読み取るか、週または月ごとに集計します。データのない期間は返されません。ゼロではありません。

必須: metrics, from, to
任意: granularity=day|week|month

curl --fail-with-body 'https://telo.health/api/v1/query_daily?metrics=steps&from=2026-11-01&to=2026-11-08&granularity=day' \
  -H "Authorization: Bearer $TELO_API_KEY"

`GET /sessions`

睡眠の夜またはワークアウトを一覧にします。ワークアウトの絞り込みと週ごとのグループ化にはkind=workoutが必要です。

必須: kind=sleep|workout, from, to
任意: activity, granularity=session|week, max_hr

curl --fail-with-body 'https://telo.health/api/v1/sessions?kind=workout&from=2026-11-01&to=2026-11-08' \
  -H "Authorization: Bearer $TELO_API_KEY"

`GET /workout_detail`

ワークアウトのサマリー、イベント、利用できる系列を読み取ります。sessionsが返したUUIDを使います。

必須: uuid
任意: metrics, offset, event_offset, limit, max_hr, wall_tolerance_s

curl --fail-with-body 'https://telo.health/api/v1/workout_detail?uuid=WORKOUT_UUID&limit=500' \
  -H "Authorization: Bearer $TELO_API_KEY"

`GET /derived_metrics`

時間ベースのトレーニング負荷と、HRVと安静時心拍数のパーソナルベースラインを読み取ります。ウォーキングはデフォルトで除外されます。

必須: from, to
任意: baseline_days=30..60 (60), include_walking=false, include_trimp=false, max_hr

curl --fail-with-body 'https://telo.health/api/v1/derived_metrics?from=2026-11-01&to=2026-11-08&include_trimp=true' \
  -H "Authorization: Bearer $TELO_API_KEY"

コード例

例ではカタログだけを読み取ります。APIキーはソースファイルではなく環境変数に置いてください。レスポンスを使う前に、HTTPの失敗を処理する必要があります。

Python

import json
import os
from urllib.request import Request, urlopen

request = Request(
    "https://telo.health/api/v1/list_metrics",
    headers={"Authorization": "Bearer " + os.environ["TELO_API_KEY"]},
)
# urlopen raises HTTPError for non-success responses.
with urlopen(request, timeout=30) as response:
    catalog = json.load(response)
print(catalog)

JavaScript (Node.js)

// Node.js, server-side only.
const response = await fetch("https://telo.health/api/v1/list_metrics", {
  headers: { Authorization: `Bearer ${process.env.TELO_API_KEY}` },
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) throw new Error(`telo HTTP ${response.status}`);
const catalog = await response.json();
console.log(catalog);

レスポンスの読み方

query_dailyのレスポンス例（架空のデータ）:

{
  "rows": [
    {
      "period": "2026-11-01",
      "metric": "steps",
      "unit": "count",
      "value": 8200,
      "aggregation": "sum",
      "days_present": 1,
      "days_expected": 1,
      "period_start": "2026-11-01",
      "period_end": "2026-11-01",
      "daily_min": 8200,
      "daily_max": 8200
    }
  ],
  "truncated": false
}

days_presentは値が保存されている日数、days_expectedはリクエストした暦上のカバー範囲を示します。データの欠けやnullはゼロではありません。単位と、タイムスタンプのローカルオフセットはそのまま扱ってください。APIはiPhoneが同期したものを読み取ります。呼び出しても同期は始まりません。ワークアウトのサマリーは永続的に保存され、生の系列は30日間保持されます。GPSは含まれません。

制限とページング

アカウントごとに1分あたり60リクエストで、すべてのキーで共有されます。429を受け取ったら、Retry-Afterの秒数だけ待ってください。
日付指定のクエリは1回あたり最大3,660日、derived_metricsは366日までです。query_dailyはカンマ区切りで最大256個の指標名を受け付けます。
日付ベースの読み取りは最大500行を返します。truncatedがtrueの場合は部分的なレスポンスを破棄し、指標を減らすか、週や月の区切りにそろえた重ならない小さな範囲で問い合わせてください。部分的な平均を、期間全体の値として扱わないでください。
workout_detailは、next_offsetとnext_event_offsetを別々に使います。両方がnullになるまで、それぞれ独立にたどってください。デフォルト: offset=0、event_offset=0、limit=360。limitの上限は500です。metrics=を空にすると、系列なしでメタデータとイベントを返します。

エラー

400: パラメータ、日付、範囲のいずれかが無効です。OpenAPIリファレンスを確認してください。
401: パーソナルキーがないか、無効か、取り消されています。必要なら新しいキーを作成してください。
403: 有料のProサブスクリプションが有効ではありません。iPhoneで「アカウント」→「プラン」を確認してください。
429: レート制限に達しました。Retry-Afterの秒数だけ待ってから再試行してください。
500: 内部エラーです。しばらくしてから再試行してください。レスポンスを、健康データが空という意味に解釈しないでください。
503: サブスクリプションを確認できません。しばらくしてから再試行してください。