Haz tu primera solicitud

Suscríbete a Pro en la app de telo para iPhone, en Cuenta → Plan, y sincroniza tu historial.
Abre Cuenta en el panel web y crea una clave para tu proyecto. Guárdala ahora: el secreto completo solo se muestra una vez.
Define TELO_API_KEY en el entorno de tu servidor o en tu terminal local y ejecuta la solicitud de abajo.

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

Autenticación

Envía Authorization: Bearer <clave> en cada solicitud. Cada clave lee solo su propia cuenta. Guárdala en tu servidor o en tu ordenador, nunca en código del navegador, en un repositorio público ni en una URL. Las cookies y los tokens del iPhone no autentican esta API.

Crea hasta cinco claves y revoca cada proyecto por separado en Cuenta. La revocación sigue disponible cuando Pro caduca. Se requiere un derecho de acceso Pro de pago incluso en las cuentas de miembros fundadores; los reembolsos y los cambios de suscripción siguen la caché de facturación existente, de hasta 15 minutos, con invalidación por webhook.

Gestionar claves de API

Endpoints

URL base: https://telo.health/api/v1. Todos los endpoints usan GET y devuelven el mismo JSON que su herramienta de lectura MCP, sin el envoltorio MCP. Las fechas usan YYYY-MM-DD. Las listas usan comas; los booleanos usan true o false. Los parámetros desconocidos o repetidos se rechazan.

`GET /data_status`

Comprueba la cobertura, el progreso de la importación y la última sincronización antes de interpretar registros que faltan.

Obligatorios: Ninguno
Opcionales: Ninguno

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

`GET /list_metrics`

Descubre los nombres, las unidades y los periodos de las métricas disponibles en tu cuenta.

Obligatorios: Ninguno
Opcionales: Ninguno

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

`GET /query_daily`

Lee valores diarios o agrégalos por semana o por mes. Los periodos sin datos no aparecen; no son cero.

Obligatorios: metrics, from, to
Opcionales: 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`

Lista noches de sueño o entrenamientos. Los filtros de entrenamiento y la agrupación semanal requieren kind=workout.

Obligatorios: kind=sleep|workout, from, to
Opcionales: 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`

Lee el resumen de un entrenamiento, sus eventos y las series disponibles. Usa un UUID devuelto por sessions.

Obligatorios: uuid
Opcionales: 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`

Lee la carga de entrenamiento basada en la duración y las referencias personales de VFC y frecuencia cardiaca en reposo. Caminar queda excluido por defecto.

Obligatorios: from, to
Opcionales: 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"

Ejemplos de código

Los ejemplos solo leen el catálogo. Tu clave de API va en el entorno, no en el archivo de código. Gestiona los errores HTTP antes de usar la respuesta.

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

Cómo leer la respuesta

Respuesta ilustrativa de query_daily, con datos ficticios:

{
  "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 cuenta los días con valores guardados; days_expected describe la cobertura de calendario solicitada. Los datos que faltan y null no son cero. Conserva las unidades y el desfase local de las marcas de tiempo. La API lee lo que el iPhone ha sincronizado; llamarla no inicia una sincronización. Los resúmenes de entrenamiento son permanentes, mientras que las series sin procesar se conservan 30 días. No incluye GPS.

Límites y paginación

60 solicitudes por minuto por cuenta, compartidas entre todas sus claves. Si recibes un 429, espera los segundos que indique Retry-After.
Como máximo 3660 días por consulta de fechas, o 366 en derived_metrics. query_daily acepta hasta 256 nombres de métrica separados por comas.
Las lecturas por fecha devuelven hasta 500 filas. Si truncated es true, descarta la respuesta parcial y consulta menos métricas o periodos más pequeños que no se solapen, alineados con semanas o meses completos. No trates una media parcial como un periodo completo.
workout_detail usa valores separados de next_offset y next_event_offset. Sigue cada uno por separado hasta que ambos sean null. Valores por defecto: offset=0, event_offset=0, limit=360; limit es como máximo 500. Un metrics= vacío devuelve metadatos y eventos sin series.

Errores

400: Parámetros, fechas o periodo no válidos. Consulta la referencia de OpenAPI.
401: Clave personal ausente, no válida o revocada. Crea una clave nueva si hace falta.
403: No hay una suscripción Pro de pago activa. Revisa Cuenta → Plan en el iPhone.
429: Se alcanzó el límite de solicitudes. Espera los segundos de Retry-After antes de reintentar.
500: Error interno. Vuelve a intentarlo más tarde; no interpretes la respuesta como datos de salud vacíos.
503: La verificación de la suscripción no está disponible. Vuelve a intentarlo más tarde.