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

MethodPathWhat it does
GET/realtime-measuresList your realtime measures, oldest first
GET/realtime-measures/{measureId}Read the essentials of one realtime measure
GET/realtime-measures/{measureId}/outputsDownload 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
}
FieldWhat it is
measureIdNames the realtime measure.
statusrunning while the session is open, ended once it was closed properly, abandoned when it stopped without closing.
createdAt, endedAtWhen the session opened, and when it was closed properly — null while it is open, or when it was abandoned.
durationHow 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.

ParameterWhat it does
takeHow many to return: 100 by default, 1000 at most.
skipHow many to skip before the first one returned.
createdFrom, createdToOnly 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}}}
FieldWhat it is
timeThe capture time of this instant, in milliseconds on the session’s scale, which starts at 0.
signalsThe 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.
variablesThe 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.

ParameterWhat it does
from, toOnly 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.

EnvironmentAPI base
Productionhttps://api.saphere.ai
Testhttps://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