Je gegevens uit de Gezondheid-app, via REST.

Doe je eerste verzoek

1. Neem Pro in de telo-app voor iPhone onder Account → Abonnement en synchroniseer daarna je geschiedenis.
2. Open Account in het webdashboard en maak een sleutel voor je project. Bewaar hem meteen: het volledige geheim wordt maar één keer getoond.
3. Zet TELO_API_KEY in de omgeving van je server of je lokale shell en voer daarna het verzoek hieronder uit.

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

Authenticatie

Stuur Authorization: Bearer <sleutel> mee met elk verzoek. Elke sleutel leest alleen zijn eigen account. Bewaar hem op je server of je eigen computer, nooit in browsercode, een openbare repository of een URL. Cookies en iPhone-tokens authenticeren deze API niet.

Maak tot vijf sleutels en trek de toegang van elk project afzonderlijk in via Account. Intrekken blijft mogelijk nadat Pro is verlopen. Ook voor founder-accounts is een betaald Pro-recht vereist; terugbetalingen en wijzigingen in het abonnement volgen de bestaande factureringscache, tot 15 minuten, die door de webhook ongeldig wordt gemaakt.

Endpoints

Basis-URL: https://telo.health/api/v1. Elk endpoint gebruikt GET en geeft dezelfde JSON terug als de bijbehorende MCP-leestool, zonder de MCP-envelop. Datums gebruiken YYYY-MM-DD. Lijsten gebruiken komma's; booleans gebruiken true of false. Onbekende of herhaalde parameters worden geweigerd.

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

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

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"

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"

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

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"

Codevoorbeelden

De voorbeelden lezen alleen de catalogus. Je API-sleutel hoort in de omgeving, niet in het bronbestand. Vang HTTP-fouten af voordat je het antwoord gebruikt.

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);

Het antwoord lezen

Illustratief antwoord van query_daily, met fictieve gegevens:

{
  "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 telt de dagen met opgeslagen waarden; days_expected beschrijft de gevraagde kalenderdekking. Ontbrekende gegevens en null zijn niet nul. Behoud de eenheden en de lokale offset van tijdstempels. De API leest wat de iPhone heeft gesynchroniseerd; een verzoek start geen synchronisatie. Samenvattingen van workouts zijn permanent; ruwe reeksen worden 30 dagen bewaard. Gps zit er niet bij.

Limieten en paginering

• 60 verzoeken per minuut per account, gedeeld door al zijn sleutels. Bij 429 wacht je het aantal seconden uit Retry-After.
• Maximaal 3.660 dagen per datumquery, of 366 voor derived_metrics. query_daily accepteert tot 256 namen van statistieken, gescheiden door komma's.
• Leesverzoeken op datum geven maximaal 500 rijen terug. Als truncated true is, gooi het gedeeltelijke antwoord weg en vraag minder statistieken op, of kleinere periodes die niet overlappen en samenvallen met volledige weken of maanden. Behandel een gedeeltelijk gemiddelde niet als een volledige periode.
• workout_detail gebruikt aparte waarden voor next_offset en next_event_offset. Volg ze los van elkaar tot ze allebei null zijn. Standaard: offset=0, event_offset=0, limit=360; limit is maximaal 500. Een lege metrics= geeft metadata en gebeurtenissen terug, zonder reeksen.

Fouten

400

Ongeldige parameters, datums of periode. Raadpleeg de OpenAPI-referentie.

401

Persoonlijke sleutel ontbreekt, is ongeldig of is ingetrokken. Maak zo nodig een nieuwe sleutel.

403

Er is geen actief betaald Pro-abonnement. Controleer Account → Abonnement op je iPhone.

429

Limiet bereikt. Wacht het aantal seconden uit Retry-After en probeer het dan opnieuw.

500

Interne fout. Probeer het later opnieuw; lees het antwoord niet als lege gezondheidsgegevens.

503

Controle van het abonnement is niet beschikbaar. Probeer het later opnieuw.