Realtime measures
Your realtime sessions, read afterwards from your own server: what they were, and what they sent back.
A realtime session sends its results while it runs. These routes give them to you afterwards: the essentials of each session — whether it is still open, when it opened and closed, how long it lasted — and the outputs it recorded, as a stream. They are authenticated with your API key, like the rest of the API, and only ever see the realtime measures of the account that key belongs to.
The routes
| Method | Path | What it does |
|---|---|---|
GET | /realtime-measures | List your realtime measures, oldest first |
GET | /realtime-measures/{measureId} | Read the essentials of one realtime measure |
GET | /realtime-measures/{measureId}/outputs | Download what one realtime measure sent back, one line per instant |
The identifier of a measure is announced to the session as it opens: the session output of the protocol, realtime:started and getMeasureId() in the library. The list finds it too, and so does the console, under Measures › Realtime.
These answers grow, they do not change
Fields, lines, signals and vitals may be added to any answer at any time: ignore those you do not know. A change that would break a reader is published as a new route, never made to an existing one.One measure
{
"measureId": "3f1a0c5e-9b2d-4a6f-8c1e-7d0b5a4e3f21",
"status": "ended",
"createdAt": "2026-11-17T10:00:00.000Z",
"endedAt": "2026-11-17T10:02:30.000Z",
"duration": 148983
}
| Field | What it is |
|---|---|
measureId | Names the realtime measure. |
status | running while the session is open, ended once it was closed properly, abandoned when it stopped without closing. |
createdAt, endedAt | When the session opened, and when it was closed properly — null while it is open, or when it was abandoned. |
duration | How long the recorded session lasts, in milliseconds: the time of the last thing recorded, the session’s time starting at 0. null when nothing recorded carries a time. |
It returns none of the data itself: the outputs have their own route, below.
The list
GET /realtime-measures returns your measures in that same shape, oldest first: a measure opened while you page through them joins the end without shifting the pages already read.
| Parameter | What it does |
|---|---|
take | How many to return: 100 by default, 1000 at most. |
skip | How many to skip before the first one returned. |
createdFrom, createdTo | Only the measures opened within [createdFrom, createdTo[, as ISO 8601 dates or instants — UTC when no offset is given. Both are optional; two windows that follow each other do not overlap. |
An empty or reversed window answers 400.
The outputs
GET /realtime-measures/{measureId}/outputs returns what the session sent back, one JSON object per line (newline-delimited JSON, application/x-ndjson), in the order of time. Each line is one instant: its time, then what was said at that 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}}}
| Field | What it is |
|---|---|
time | The capture time of this instant, in milliseconds on the session’s scale, which starts at 0. |
signals | The waveforms that have a point at this instant, by name — hr (the pulse) and br (the breathing) — each { index, value } as in the protocol. index is the capture the point belongs to: it skips where a capture had nothing to measure, and that gap is what tells a missing stretch from a continuous one. |
variables | The vitals computed at this instant: the variables message of the session, without its time. |
A key is absent when nothing was said at that instant — never null. Most lines carry only hr; variables comes about once a second, on the line of the instant it was computed for.
| Parameter | What it does |
|---|---|
from, to | Only the instants within [from, to[, in milliseconds on the session’s scale. Both are optional: the whole recording otherwise. Two windows that follow each other do not overlap. |
The response is read as it is written: it does not need to fit in memory, on either side, however long the session — read it line by line rather than as one document. It is compressed when your client accepts it. A session that is still open returns what has been recorded so far, a minute at a time; a session that was not recorded, or a window with nothing in it, returns an empty body. For a session under way, read its outputs on the session itself.
An empty or reversed window answers 400, and so does a bound that is not a whole number of milliseconds. A request whose Accept excludes both application/x-ndjson and */* answers 406. Every line ends with a newline: a last line without one is a response cut on the way, not the end of the recording.
Times
Every time of a realtime session starts at 0: the timeOrigin you gave when opening it is subtracted from the time of every frame on arrival, and everything kept or returned is on that scale — the time of the hr, br and variables messages, duration, and the time, from and to of the outputs. A duration read here is therefore the end of the waveforms you drew during the session, with nothing to convert.
During its first minute, a session that is still open has a null duration and no outputs yet. A session that was not recorded answers with a null duration and an empty stream, which is not an error.
Errors
A request without a valid API key answers 401. A measure that does not exist and a measure that belongs to another account answer the same 404: nobody can probe for the measures of other accounts. An identifier that is not a UUID answers 400.
Worked example
The commands below run against Production. The same calls on Test differ only in the address.
| Environment | API base |
|---|---|
| Production | https://api.saphere.ai |
| Test | https://api.test.saphere.ai |
A key issued for one environment is never valid on the other, and a realtime measure exists only on the environment that measured it. See Environments.
# Your realtime measures of 17 November
curl -s "https://api.saphere.ai/realtime-measures?createdFrom=2026-11-17&createdTo=2026-11-18" \
-H "Authorization: Bearer $SAPHERE_API_KEY"
# One of them
curl -s https://api.saphere.ai/realtime-measures/3f1a0c5e-9b2d-4a6f-8c1e-7d0b5a4e3f21 \
-H "Authorization: Bearer $SAPHERE_API_KEY"
# Its second minute of outputs, compressed on the wire, one instant per line
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