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éthode | Chemin | Ce qu’elle fait |
|---|---|---|
GET | /realtime-measures | Lister 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}/outputs | Té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
}
| Champ | Ce que c’est |
|---|---|
measureId | Nomme la mesure temps réel. |
status | running tant que la session est ouverte, ended une fois fermée proprement, abandoned quand elle s’est arrêtée sans fermeture. |
createdAt, endedAt | Quand 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. |
duration | Combien 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ètre | Ce qu’il fait |
|---|---|
take | Combien en rendre : 100 par défaut, 1000 au plus. |
skip | Combien en passer avant la première rendue. |
createdFrom, createdTo | Seulement 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}}}
| Champ | Ce que c’est |
|---|---|
time | Le temps de capture de cet instant, en millisecondes sur l’échelle de la session, qui commence à 0. |
signals | Les 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. |
variables | Les 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ètre | Ce qu’il fait |
|---|---|
from, to | Seulement 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.
| Environnement | Base de l'API |
|---|---|
| Production | https://api.saphere.ai |
| Test | https://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