--- title: "Read a window of a realtime session" method: GET path: "/v2/realtime/session/{session_id}/window" tags: ["Realtime Emotion API"] --- # Read a window of a realtime session `GET /v2/realtime/session/{session_id}/window` ## Request - Base URL: `https://api.imentiv.ai` (the document declares no server; this is the origin it was published from) - URL: `https://api.imentiv.ai/v2/realtime/session/{session_id}/window` - Auth: one of: - API key in header `X-API-Key` - HTTP bearer - OAuth 2 - Authorization code: `https://api.imentiv.ai/oauth/authorize` - Token URL: `https://api.imentiv.ai/oauth/token` scopes: `realtime.write` Read what a session you started produced over one span: the transcript, and the emotion statistics of the streams you ask for. Use it to follow a session from your server without holding the results socket open. Reading a window does not cost credits of its own, but it is how the session is billed when you do not hold the socket: the session's time is charged, at the same per-second rate, up to its present whenever it is read and when it is ended. A caller that never reads gets no output and pays nothing. A session whose balance has run out is ended and answered 402. Every time is in milliseconds on one session clock, shared by every stream and by the words; `origin_epoch_ms` is the Unix time of its zero. The span is half-open, `[start_ms, end_ms)`. An empty or partial window is a 200: silence is data. While a stream carries the `pending` flag more of the span may still arrive, so ask again; stop once it is gone. A session started with `emotion_analysis_enabled` false ran no emotion model: asking it for a stream is a 400, and the transcript is always available. Available while the session is live and for a short time after it ends. **Authentication:** Requires valid API key in X-API-Key header. ## Path parameters - `session_id` string, required: The session ID ## Query parameters - `start_ms` integer, required: Start of the span, in milliseconds on the session clock. - `end_ms` integer, required: End of the span (exclusive). Must be greater than `start_ms`. - `modalities` string[]: Emotion streams to include, repeated: `face`, `voice`, `text`. Omit for the transcript only. ## Response `200` Successful Response - RealtimeWindow: What a live session produced over one span: the transcript and emotion statistics. - `session_id` string, required - `origin_epoch_ms` integer, required: The Unix time, in milliseconds, of the session clock's zero. - `now_ms` integer, required: The session clock when this was answered. It stops moving once the session ends. - `start_ms` integer, required: The start of the span asked for, echoed. - `end_ms` integer, required: The end of the span asked for, echoed. - `modalities` string[]: The streams asked for, echoed without repeats. - `modalities_used` string[]: The streams that had at least one reading in the window. - `per_modality` RealtimeWindowStreams: The streams asked for, one entry each, including those with no data. - `face` RealtimeWindowStream: One emotion stream's statistics over the window. - `valence` RealtimeWindowAxis: Valence or arousal over the window, from -1 to 1. - `mean` number, required: The average over the window. - `peak` number, required: The reading furthest from zero, signed. - `peak_t_ms` integer, nullable: When the peak happened, inside the window. Null if not tracked. - `arousal` RealtimeWindowAxis: Valence or arousal over the window, from -1 to 1. - `mean` number, required: The average over the window. - `peak` number, required: The reading furthest from zero, signed. - `peak_t_ms` integer, nullable: When the peak happened, inside the window. Null if not tracked. - `circumplex_version` string, nullable: The version of the scale valence and arousal are on. Windows compare only on the same version. - `top_emotions` RealtimeWindowEmotion[]: Up to three labels, the most frequent first. - `label` string, required: The emotion label. - `share` number, required: The fraction of usable data this label led, from 0 to 1. - `shifts` RealtimeWindowShift[]: Departures from baseline, by time. - `t_ms` integer, required: When it happened, inside the window. - `kind` 'onset' | 'peak' | 'offset', required: Whether the departure begins, is largest, or ends. - `magnitude` number, required: How far from the baseline, in baseline standard deviations. - `metric` string, nullable: What departed: null for the overall state, else valence, arousal or an emotion label. - `signal_quality` RealtimeWindowSignal, required: How much usable data one stream had in the window. - `coverage` number, required: The fraction of the window covered by usable data, from 0 to 1. - `samples` integer, required: How many readings fell in the window. - `processed_through_ms` integer, nullable: The session time up to which this stream is final. Null when nothing is processed yet. - `flags` string[]: Why the numbers may be thin or incomplete. `pending` means ask again. - `voice` RealtimeWindowStream: One emotion stream's statistics over the window. - `valence` RealtimeWindowAxis: Valence or arousal over the window, from -1 to 1. - `mean` number, required: The average over the window. - `peak` number, required: The reading furthest from zero, signed. - `peak_t_ms` integer, nullable: When the peak happened, inside the window. Null if not tracked. - `arousal` RealtimeWindowAxis: Valence or arousal over the window, from -1 to 1. - `mean` number, required: The average over the window. - `peak` number, required: The reading furthest from zero, signed. - `peak_t_ms` integer, nullable: When the peak happened, inside the window. Null if not tracked. - `circumplex_version` string, nullable: The version of the scale valence and arousal are on. Windows compare only on the same version. - `top_emotions` RealtimeWindowEmotion[]: Up to three labels, the most frequent first. - `label` string, required: The emotion label. - `share` number, required: The fraction of usable data this label led, from 0 to 1. - `shifts` RealtimeWindowShift[]: Departures from baseline, by time. - `t_ms` integer, required: When it happened, inside the window. - `kind` 'onset' | 'peak' | 'offset', required: Whether the departure begins, is largest, or ends. - `magnitude` number, required: How far from the baseline, in baseline standard deviations. - `metric` string, nullable: What departed: null for the overall state, else valence, arousal or an emotion label. - `signal_quality` RealtimeWindowSignal, required: How much usable data one stream had in the window. - `coverage` number, required: The fraction of the window covered by usable data, from 0 to 1. - `samples` integer, required: How many readings fell in the window. - `processed_through_ms` integer, nullable: The session time up to which this stream is final. Null when nothing is processed yet. - `flags` string[]: Why the numbers may be thin or incomplete. `pending` means ask again. - `text` RealtimeWindowStream: One emotion stream's statistics over the window. - `valence` RealtimeWindowAxis: Valence or arousal over the window, from -1 to 1. - `mean` number, required: The average over the window. - `peak` number, required: The reading furthest from zero, signed. - `peak_t_ms` integer, nullable: When the peak happened, inside the window. Null if not tracked. - `arousal` RealtimeWindowAxis: Valence or arousal over the window, from -1 to 1. - `mean` number, required: The average over the window. - `peak` number, required: The reading furthest from zero, signed. - `peak_t_ms` integer, nullable: When the peak happened, inside the window. Null if not tracked. - `circumplex_version` string, nullable: The version of the scale valence and arousal are on. Windows compare only on the same version. - `top_emotions` RealtimeWindowEmotion[]: Up to three labels, the most frequent first. - `label` string, required: The emotion label. - `share` number, required: The fraction of usable data this label led, from 0 to 1. - `shifts` RealtimeWindowShift[]: Departures from baseline, by time. - `t_ms` integer, required: When it happened, inside the window. - `kind` 'onset' | 'peak' | 'offset', required: Whether the departure begins, is largest, or ends. - `magnitude` number, required: How far from the baseline, in baseline standard deviations. - `metric` string, nullable: What departed: null for the overall state, else valence, arousal or an emotion label. - `signal_quality` RealtimeWindowSignal, required: How much usable data one stream had in the window. - `coverage` number, required: The fraction of the window covered by usable data, from 0 to 1. - `samples` integer, required: How many readings fell in the window. - `processed_through_ms` integer, nullable: The session time up to which this stream is final. Null when nothing is processed yet. - `flags` string[]: Why the numbers may be thin or incomplete. `pending` means ask again. - `words` RealtimeWindowWord[]: The final transcript overlapping the window, by start time. - `text` string, required: What was said. - `start_ms` integer, required - `end_ms` integer, required - `speaker` string, nullable: Who said it. Null unless speakers were told apart. - `words_granularity` 'word' | 'segment', required: Whether each entry of `words` is one word or a whole segment. - `words_processed_through_ms` integer, nullable: The session time up to which the transcript is final. - `words_flags` string[]: Why the transcript may be incomplete. `pending` means ask again. ## Other responses - `400`: A stream was asked for that the session was not started for (`{"detail": {"code": "modality_not_admitted"}}`): any emotion stream when the session was started with `emotion_analysis_enabled` false, or `face` on a voice-only session. - `402`: The credits for the session have run out (`{"detail": {"code": "insufficient_credits"}}`). The session has been ended. - `404`: Not a session you started, or one that has not started yet. - `409`: The span starts after the session's present, or has been dropped from every stream asked for (`{"detail": {"code": "window_out_of_range"}}`). - `410`: The server holding this session restarted or went away, and the session ended with it. The body carries `{"code": "session_node_gone"}`. Start a new session; retrying this one will not help. - `422`: Validation Error - `503`: The window could not be read right now (`{"detail": {"code": "window_unavailable"}}`). Ask again. ## Changes - **2026-10-31** `bd825cd86e8c`: 1 info - endpoint added [Operation history](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/changes/v2/realtime/session/:session_id/window/get.md) --- [API](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai.md) - [All operations](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/llms.txt) - [OpenAPI document](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/revisions/bc15cec7e794?raw)