Mesures temps réel

Vos sessions temps réel, lues après coup depuis votre propre serveur : ce qu’elles ont été, et ce qu’elles ont renvoyé.

Une session temps réel envoie ses résultats pendant qu’elle se déroule. Ces routes vous les rendent après coup : l’essentiel de chaque session — si elle est encore ouverte, quand elle s’est ouverte et fermée, combien de temps elle a duré — et les sorties qu’elle a enregistrées, en flux. Elles s’authentifient avec votre clé d’API, comme le reste de l’API, et ne voient jamais que les mesures temps réel du compte auquel appartient cette clé.

Les routes

MéthodeCheminCe qu’elle fait
GET/realtime-measuresLister vos mesures temps réel, de la plus ancienne à la plus récente
GET/realtime-measures/{measureId}Lire l’essentiel d’une mesure temps réel
GET/realtime-measures/{measureId}/outputsTélécharger ce qu’une mesure temps réel a renvoyé, une ligne par instant

L’identifiant d’une mesure est annoncé à la session dès son ouverture : la sortie session du protocole, realtime:started et getMeasureId() dans la librairie. La liste le retrouve aussi, de même que la console, sous Measures › Realtime.

Ces réponses s’enrichissent, elles ne changent pas

Des champs, des lignes, des signaux et des grandeurs peuvent s’ajouter à toute réponse, à tout moment : ignorez ceux que vous ne connaissez pas. Un changement qui casserait un lecteur est publié comme une nouvelle route, jamais apporté à une route existante.

Une mesure

{
  "measureId": "3f1a0c5e-9b2d-4a6f-8c1e-7d0b5a4e3f21",
  "status": "ended",
  "createdAt": "2026-11-17T10:00:00.000Z",
  "endedAt": "2026-11-17T10:02:30.000Z",
  "duration": 148983
}
ChampCe que c’est
measureIdNomme la mesure temps réel.
statusrunning tant que la session est ouverte, ended une fois fermée proprement, abandoned quand elle s’est arrêtée sans fermeture.
createdAt, endedAtQuand la session s’est ouverte, et quand elle a été fermée proprement — null tant qu’elle est ouverte, ou quand elle a été abandonnée.
durationCombien de temps dure la session enregistrée, en millisecondes : le temps de la dernière chose enregistrée, le temps de la session commençant à 0. null quand rien d’enregistré ne porte de temps.

Elle ne rend aucune des données elles-mêmes : les sorties ont leur propre route, plus bas.

La liste

GET /realtime-measures rend vos mesures sous cette même forme, de la plus ancienne à la plus récente : une mesure ouverte pendant que vous parcourez les pages rejoint la fin sans décaler celles déjà lues.

ParamètreCe qu’il fait
takeCombien en rendre : 100 par défaut, 1000 au plus.
skipCombien en passer avant la première rendue.
createdFrom, createdToSeulement les mesures ouvertes dans [createdFrom, createdTo[, en dates ou instants ISO 8601 — UTC quand aucun décalage n’est donné. Les deux sont facultatifs ; deux fenêtres qui se suivent ne se recouvrent pas.

Une fenêtre vide ou renversée répond 400.

Les sorties

GET /realtime-measures/{measureId}/outputs rend ce que la session a renvoyé, un objet JSON par ligne (JSON délimité par des retours à la ligne, application/x-ndjson), dans l’ordre des temps. Chaque ligne est un instant : son time, puis ce qui a été dit à cet instant.

{"time":7034,"signals":{"hr":{"index":211,"value":0.4132}},"variables":{"mature":false,"confident":true,"heartRate":72.4}}
{"time":7067,"signals":{"hr":{"index":212,"value":0.4417},"br":{"index":212,"value":3.25}}}
ChampCe que c’est
timeLe temps de capture de cet instant, en millisecondes sur l’échelle de la session, qui commence à 0.
signalsLes ondes qui ont un point à cet instant, par nom — hr (le pouls) et br (la respiration) —, chacune { index, value } comme dans le protocole. index est la capture à laquelle le point appartient : il saute là où une capture n’avait rien à mesurer, et ce trou est ce qui distingue un passage manquant d’un signal continu.
variablesLes grandeurs calculées à cet instant : le message variables de la session, sans son time.

Une clé est absente quand rien n’a été dit à cet instant — jamais null. La plupart des lignes ne portent que hr ; variables vient environ une fois par seconde, sur la ligne de l’instant pour lequel elles ont été calculées.

ParamètreCe qu’il fait
from, toSeulement les instants dans [from, to[, en millisecondes sur l’échelle de la session. Les deux sont facultatifs : tout l’enregistrement sinon. Deux fenêtres qui se suivent ne se recouvrent pas.

La réponse se lit à mesure qu’elle s’écrit : elle n’a pas à tenir en mémoire, d’un côté comme de l’autre, si longue que soit la session — lisez-la ligne à ligne plutôt que comme un seul document. Elle est compressée quand votre client l’accepte. Une session encore ouverte rend ce qui a été enregistré jusque-là, minute par minute ; une session qui n’a pas été enregistrée, ou une fenêtre où rien n’a été dit, rend un corps vide. Pour une session en cours, lisez ses sorties sur la session elle-même.

Une fenêtre vide ou renversée répond 400, de même qu’une borne qui n’est pas un nombre entier de millisecondes. Une requête dont l’en-tête Accept exclut à la fois application/x-ndjson et */* répond 406. Chaque ligne se termine par un retour à la ligne : une dernière ligne sans lui est une réponse coupée en route, pas la fin de l’enregistrement.

Les temps

Tous les temps d’une session temps réel commencent à 0 : le timeOrigin donné à son ouverture est retiré du temps de chaque image dès son arrivée, et tout ce qui est gardé ou rendu est sur cette échelle — le time des messages hr, br et variables, duration, et le time, from et to des sorties. Une duration lue ici est donc la fin des ondes que vous avez tracées pendant la session, sans rien à convertir.

Pendant sa première minute, une session encore ouverte a une duration à null et pas encore de sorties. Une session qui n’a pas été enregistrée répond par une duration à null et un flux vide, ce qui n’est pas une erreur.

Les erreurs

Une requête sans clé d’API valide répond 401. Une mesure qui n’existe pas et une mesure qui appartient à un autre compte répondent le même 404 : personne ne peut sonder les mesures des autres comptes. Un identifiant qui n’est pas un UUID répond 400.

Exemple complet

Les commandes ci-dessous visent la Production. Les mêmes appels sur Test ne diffèrent que par l’adresse.

EnvironnementBase de l'API
Productionhttps://api.saphere.ai
Testhttps://api.test.saphere.ai

Une clé émise sur un environnement n’est jamais valable sur l’autre, et une mesure temps réel n’existe que sur l’environnement qui l’a mesurée. Voir Environnements.

# Vos mesures temps réel du 17 novembre
curl -s "https://api.saphere.ai/realtime-measures?createdFrom=2026-11-17&createdTo=2026-11-18" \
  -H "Authorization: Bearer $SAPHERE_API_KEY"

# L'une d'elles
curl -s https://api.saphere.ai/realtime-measures/3f1a0c5e-9b2d-4a6f-8c1e-7d0b5a4e3f21 \
  -H "Authorization: Bearer $SAPHERE_API_KEY"

# Sa deuxième minute de sorties, compressée sur le fil, un instant par ligne
curl -s --compressed "https://api.saphere.ai/realtime-measures/3f1a0c5e-9b2d-4a6f-8c1e-7d0b5a4e3f21/outputs?from=60000&to=120000" \
  -H "Authorization: Bearer $SAPHERE_API_KEY" > outputs.ndjson