# HCIs and results

This page says what each field is. What to show first, what arrives in each case and how to read again without paying: [Show and use the results](/docs/guides/show-results/).

## Human Context Indicators

An **HCI** is an indicator of the interaction, traceable to the signal. Neurologyca's catalogue has three levels: HCIs, meta-indicators (MCI) and raw indicators (RCI). No context uses every indicator, and being in the catalogue does not mean every indicator has the same level of validation.

**The catalogue and what you receive.** The table below is the public catalogue, and it is provisional. Which indicators you receive depends on the context and on your organization's agreement; today it can be the whole public catalogue. Every interpreted context includes the ones its interpretation needs. The list of each protocol is in **Your integration › Protocols** ([Your integration](/docs/access/account/#your-integration)); an indicator that arrives in an example and not in your capture is [this pitfall](/docs/resources/pitfalls/#pf-hci-not-in-your-context). To receive more, ask Neurologyca.

The public catalogue groups them by what they describe. If your context includes them, each one arrives with the name of the **Key in `/results`** column, exactly as it arrives in `rawResults` and `aggResults` (for example, Workload arrives as `workload_model`), so you can find each indicator in your data. Four of them, Disengagement, Mental Fatigue Load, Emotional Mental Control and Facial Muscle Tension, do not arrive in `/results`. The **Complex emotions** (Anticipation, Trust, Awe and the rest of their group) arrive in every frame, like the basic ones: Engine computes each one from two basic emotions, so several of them never reach 100; the Scale column gives the range each one can take.

| Indicator | Group | Key in `/results` | When it arrives | Scale |
| --- | --- | --- | --- | --- |
| Attention | Attention | `Attention` | In every frame, from the first | 0/1 per frame; its mean in `/results` is the fraction of frames with attention, 0–1 |
| Effective Active Attention · Preview | Attention | `effective_active_attention` | One value per session, in `session` (`{ v, n }`: `v` is the 0–100 share of the measured frames with Attention = 1 and `n` its denominator); never per frame | 0..100 |
| Disengagement · Preview | Attention | not in `/results` | **Warm-up: 5 sessions.** From the 6th session, in a step with at least 60 s of valid face (in practice about 66–76 s in a row). Per step or per session, only used for the interpretation (`/analyze`); no route returns its value today; not yet in Engine production | 0..100 |
| Workload | Cognition | `workload_model` | After ~5 s from the start of the step, then 1 in ~6 frames; in a step shorter than ~5 s it does not arrive. If the step follows the previous one without a pause, from frame 1 | 0..100 |
| Coherence | Cognition | `Coherence` | In every frame, from the first | 0..100 |
| Comprehension | Cognition | `Comprehension` | In every frame, from the first; Engine computes it over a session window, so each value depends on the whole step | 0..100 |
| Confusion | Cognition | `Confusion` | In every frame, from the first; Engine computes it over a session window, so each value depends on the whole step | 0..100 |
| Mental Fatigue Load · Preview | Cognition | not in `/results` | **Warm-up: 5 sessions.** From the person's 6th session in that context: it needs 5 previous completed sessions, and the baseline does not count. Per step or per session, only used for the interpretation (`/analyze`); no route returns its value today; not yet in Engine production | 0..100 |
| Joy | Emotions | `Joy` | In every frame, from the first | 0..100 |
| Sadness | Emotions | `Sadness` | In every frame, from the first | 0..100 |
| Surprise | Emotions | `Surprise` | In every frame, from the first | 0..100 |
| Anger | Emotions | `Anger` | In every frame, from the first | 0..100 |
| Disgust | Emotions | `Disgust` | In every frame, from the first | 0..100 |
| Fear | Emotions | `Fear` | In every frame, from the first | 0..100 |
| Neutral | Emotions | `Neutral` | In every frame, from the first | 0..100 |
| Anticipation | Complex emotions | `Anticipation` | In every frame, from the first | 0 or 50 |
| Anxiety | Complex emotions | `Anxiety` | In every frame, from the first | 0..75 |
| Awe | Complex emotions | `Awe` | In every frame, from the first | 0..100 |
| Contempt | Complex emotions | `Contempt` | In every frame, from the first | 0..100 |
| Curiosity | Complex emotions | `Curiosity` | In every frame, from the first | 0..87.5 |
| Cynicism | Complex emotions | `Cynicism` | In every frame, from the first | 0..75 |
| Delight | Complex emotions | `Delight` | In every frame, from the first | 0..100 |
| Despair | Complex emotions | `Despair` | In every frame, from the first | 0..100 |
| Disapproval | Complex emotions | `Disapproval` | In every frame, from the first | 0..100 |
| Envy | Complex emotions | `Envy` | In every frame, from the first | 0..100 |
| Guilt | Complex emotions | `Guilt` | In every frame, from the first | 0..100 |
| Hope | Complex emotions | `Hope` | In every frame, from the first | 0..62.5 |
| Love | Complex emotions | `Love` | In every frame, from the first | 0..87.5 |
| Morbidness | Complex emotions | `Morbidness` | In every frame, from the first | 0..100 |
| Outrage | Complex emotions | `Outrage` | In every frame, from the first | 0..100 |
| Pessimism | Complex emotions | `Pessimism` | In every frame, from the first | 0..75 |
| Pride | Complex emotions | `Pride` | In every frame, from the first | 0..100 |
| Remorse | Complex emotions | `Remorse` | In every frame, from the first | 0..100 |
| Shame | Complex emotions | `Shame` | In every frame, from the first | 0..100 |
| Submission | Complex emotions | `Submission` | In every frame, from the first | 0..87.5 |
| Trust | Complex emotions | `Trust` | In every frame, from the first | 0..75 |
| Unbelief | Complex emotions | `Unbelief` | In every frame, from the first | 0..100 |
| Valence | Circumplex | `valence` | In every frame, from the first | −100..100 |
| Arousal | Circumplex | `arousal` | In every frame, from the first | 0..100 |
| Interest | Mood and regulation | `Interest` | In every frame, from the first; Engine computes it over a session window, so each value depends on the whole step | 0..100 |
| Frustration | Mood and regulation | `Frustration` | In every frame, from the first; Engine computes it over a session window, so each value depends on the whole step | 0..100. Engine is reviewing its scale. |
| Rejection | Mood and regulation | `Rejection` | In every frame, from the first; Engine computes it over a session window, so each value depends on the whole step | 0..100 |
| Stress intensity | Mood and regulation | `Stress_intens` | In every frame, from the first; each value is scaled over the whole session (min-max), so it depends on the whole step | 0..100 |
| Motivation | Mood and regulation | `faa` | After ~5 s from the start of the step, then 1 in ~6 frames; in a step shorter than ~5 s it does not arrive. If the step follows the previous one without a pause, from frame 1 | −100..100. Not valid, do not use: it arrives out of its range and Engine is replacing its model. |
| Emotional Mental Control · Preview | Mood and regulation | not in `/results` | **Warm-up: 5 sessions.** From the 6th session, in uninterrupted 3-minute blocks (a shorter session has no value); the Engine model is provisional. Per step or per session, only used for the interpretation (`/analyze`); no route returns its value today; not yet in Engine production | 0..100 |
| Facial Muscle Tension · Preview | Mood and regulation | not in `/results` | **Warm-up: 0 or 5 sessions.** From the 1st session if the context already has Neurologyca calibration data; otherwise from the 6th. Per step or per session, only used for the interpretation (`/analyze`); no route returns its value today; not yet in Engine production | 0..100 |

**When each one arrives.** Most indicators arrive in every frame from the first. Stress intensity, Comprehension, Confusion, Interest, Frustration and Rejection also have a value from the first frame, but Engine computes them over the whole session, so each value depends on the whole step. Workload (`workload_model`) and Motivation (`faa`) need a warm-up: nothing for about the first 5 seconds of each step (or after a pause), then one value about every 6 frames and `null` in the rest; a step shorter than about 5 seconds does not carry the key at all, and a step continuous with the previous one, without a pause, has values from the first frame. Disengagement, Mental Fatigue Load, Emotional Mental Control and Facial Muscle Tension are computed per step or per session, not per frame, and are only used for the interpretation (`/analyze`); no route returns their values today. They need previous sessions of the person: see [Indicators that need previous sessions](#indicators-that-need-previous-sessions).

Read the models as what they are: displayed emotion, not felt; valence as an observer would perceive it; **arousal as expressive intensity**, not physiological activation (in the playground it is shown next to Valence, as expressive intensity); workload as a facial proxy of cognitive load.

**Scales.** The indicators run from 0 to 100, except Valence and Motivation, from −100 to 100, and Attention: it is 0 or 1 per frame, and its mean in `/results` is the fraction of frames with attention (0 to 1). **Motivation (`faa`) is not valid: do not use it.** It arrives, but out of the range Engine declares for it (0 to 100), and Engine is replacing its model.

## Indicators that need previous sessions

Four indicators compare the current session with the person's history, so they have no value until that history exists. Each entry of the history is one completed protocol session of the same person in the same context; the baseline does not count, and Engine keeps the last 20.

- **Mental Fatigue Load**: 5 previous sessions, so a value from the person's 6th session in that context.
- **Facial Muscle Tension**: from the 1st session if the context already has Neurologyca calibration data; otherwise, from the 6th.
- **Disengagement**: 5 previous sessions, and a step with at least 60 s of valid face.
- **Emotional Mental Control**: 5 previous sessions, and uninterrupted 3-minute blocks; a shorter session has no value.

Even from the 6th session they do not arrive in `/results`: Engine uses them only inside the interpretation (`/analyze`), and does not compute them in production yet. All four are **Preview**. In DevLab (Results, the deferred mode and the recorded examples) they appear as **Locked**, with their warm-up, because no route returns their value.

## The shape of the results

`GET /results/{userProtocolId}/{protocolMechanicId}` returns, per step:

```json
{
  "rawResults": {
    "1": {
      "<frameId-1>": {
        "hcis": {
          "valence": -0.343,
          "arousal": 64.313,
          "Confusion": 14.326,
          "Stress_intens": 64.183,
          "…": "64 signals in total; this example shows 4"
        },
        "timestamp": 1767225600000
      }
    }
  },
  "aggResults": {
    "1": {
      "mean": {
        "valence": 6.751,
        "arousal": 69.775,
        "Confusion": 14.618,
        "Stress_intens": 54.195,
        "…": "64 signals in total; this example shows 4"
      }
    }
  }
}
```

- `rawResults`: per step and per frame, the indicators and the capture time.
- `aggResults`: per step, the mean.
- Always from the last **completed** capture of that position. Until the capture completes, `rawResults` and `aggResults` come back empty: poll.
- `GET /results/{userProtocolId}` returns every position as `{ userProtocolId, mechanics[] }`: one item per mechanic, each with its own `rawResults`, `aggResults` and `speech`. `…/{stepOrder}` returns a single step, with its `stepOrder`.
- The signals of the examples on this page come from a test capture made before the indicators depended on the context: with your context you can receive fewer.
- The playground shows Workload (`workload_model`) when it arrives; it does not show Motivation (`faa`), which is not valid.

Read `rawResults` as one row per frame: sort it by `timestamp` and treat a missing key as a gap, never as zero. Frames sent without `featuresMeta` are counted in `framesWithoutFeaturesMeta` of each `202` (see [Capturing for the best accuracy](/docs/concepts/capture/)). A jump in time between consecutive frames usually means frames that never arrived, such as a pause of the camera or of the tab. Open a real capture in the [playground](/playground#results).

Before the capture completes:

```json
{ "rawResults": {}, "aggResults": {} }
```

### `speech`

The three `/results` routes also return `speech`: what was asked and what was said in each step. This is only in the test environment's Engine. In `GET /results/{userProtocolId}` it goes inside each item of `mechanics[]`. A Measurement capture with voice, which shows no question:

```json at="body"
{
  "speech": {
    "1": { "transcript": "I usually start the day by checking my plan for the morning." }
  }
}
```

- It uses the same keys as `aggResults`, the step's order. A step appears only when it has `questionText` or `transcript`, never `""` or `null`; with nothing to show, `speech` is `{}`.
- `questionText` is the step's question, in the language of the person's narrative (`narrative.language`), not the one it was shown or spoken in. A person without that language gets no `questionText`.
- `transcript` is the speech your app sent for that step (`sttByStep`, see [Send the transcript](/docs/api/#send-the-transcript)), stored as sent. Speech that could not be placed in a step is not here, so joining the `transcript` values is not the full transcript.
- When a protocol shows the question in one step and the answer in the next (the answer step has `media_from: previous_step`), `questionText` arrives in the question's step and `transcript` in the answer's.
- It is the same in real time and deferred, and it does not depend on which indicators your context includes. The interruption route does not carry it.

### `session`

The three `/results` routes also return `session`: values of the whole session, keyed by indicator, neither per frame like `rawResults` nor per step like `aggResults`. Today it only carries Effective Active Attention (`effective_active_attention`), and it is **Preview**. In `GET /results/{userProtocolId}` it goes inside each item of `mechanics[]`.

```json
{ "session": { "effective_active_attention": { "v": 83.33, "n": 1247 } } }
```

- `v` goes from 0 to 100: the percentage of the session's measured frames with `Attention = 1`, and it is not the 0 to 1 mean of `aggResults.mean.Attention`.
- `n` is its denominator, the measured frames: 100 over 30 frames is not the same evidence as 100 over 20 000.
- The single-step route carries it too, for the whole session.
- `null` means it was not measured (which is not 0) or that your context does not include it. On the interruption route it is `null`.
- It can also arrive `null` in the read right after the Final, even when it was measured (seen in the test environment's Engine, by the SDK path): read `/results` again a little later before showing it as missing.

### Means across steps

`aggResults` gives one mean per step. Engine does not give the mean of a question that spans two steps, nor of the whole session, except the session value of the relevant indicators (`measured_value` of [`selected_ehcis[]`](#preview-fields), with an interpretation) and [`session`](#session), which today carries only Effective Active Attention. To get the mean of several steps, add up the values of every frame of `rawResults` in those steps and divide by how many frames carry the key; never average the step means, which weighs a short step as much as a long one. With the SDK this is done for you: `hcis` is the mean of every frame of the session and `hcisByStep` the mean of the frames of each step (from `retrieveResults` or the outcome of `stop()`).

## Keys you can rely on

The payload carries more keys than the public catalogue, keys are case-sensitive, and their spelling is not always the catalogue name (`Stress_intens` for Stress intensity). Build on the documented indicators only.

> The list of public indicators is provisional: which HCIs are public is being confirmed with Engine. Which of them you receive depends on the context and on your organization's agreement, which can change. Keep your code tolerant of an indicator that appears or goes away.

## Live events

`GET /stream/{userProtocolId}` is a Server-Sent Events stream for one enrolment. Send the token as `Authorization: Bearer`.

| Event | When |
| --- | --- |
| `connected` | The stream opens |
| `processing.error` | Something failed while processing a capture: `{ errorCategory, stage, final, message }` |
| `hci.warning` | A warning about an indicator, once per batch, and only for an indicator your context includes. It is not an alert; DevLab does not show the level that triggers it (`threshold`), so do not build on it. Whether it is sent depends on the environment |
| `session.abandoned` | A capture was abandoned |
| `interruption.offered` | A microintervention is offered |
| `results.ready` | The position's capture is complete and its indicators are ready, with no interpretation to wait for; `payload` carries `analysis` (`false`), `reason` and `results`, the path to read |
| `constellation.complete` | An interpretation is ready, when you asked for it on the last batch. It carries the analysis without `structured_data.temporal_profile.trajectory` (one entry per frame): read that with `POST /analyze`, which serves the stored one |
| `stream.end` | The server closes the stream; `reason` says why |

In a capture of the sample, the stream sent `connected`, `hci.warning` and `results.ready`; an abandoned capture also sent `session.abandoned`.

`results.ready` arrives once per position, when its capture is complete: that is when `/results` returns its data. Do not wait for a given `stepOrder`: it is not always the last step's. In a position that asked for the interpretation it normally does not arrive; `constellation.complete` does. In rare cases it can arrive twice, or together with `constellation.complete`. `reason` says why there is no interpretation: `analysis_not_requested` (no batch asked for it, as with the Measurement kit, `triggerAnalysis: false`) or `protocol_not_interpreted` (a batch asked for it, but the protocol is never interpreted, such as Measurement). If the interpretation fails, the stream sends `processing.error`: the indicators can already be read, and `constellation.complete` can still arrive after Engine retries. Keep polling `/results` as a fallback.

`processing.error` says which part failed in `stage` (`emotion_analysis`, `hci_calculation`, `step_aggregation`, `interpretation` or `processing`) and whether it is over in `final`: with `final: false` Engine retries on its own, so the indicators or a `constellation.complete` may still arrive; with `final: true` nothing more is tried for that capture. `message` is in English and carries no ids.

You may also see `lite.complete` on the stream: a preliminary analysis that is not part of the public Engine 2 API (see [Migration](/docs/resources/migration/)). Never treat it as the interpretation.

## Interpretation for an audience

When the context has a taxonomy, `POST /analyze` returns an interpretation written for an `audience`, taken from the request or from the user's profile; without either, the default reading. The same capture can be narrated for different audiences without measuring again, and each one is cached.

Rely on these fields: `interpretation`, `structured_data.insight`, `structured_data.headline`, `structured_data.sections[]`, `warnings`, `from_cache` and `audience_applied`. How the analysis came out is `metadata.status`, one of `complete`, `degraded` or `failed`; `degraded` can also mean that the reading lacked an indicator your context does not include. What to show in each case: [What to show first](/docs/guides/show-results/#what-to-show-first).

| Field | What it is |
| --- | --- |
| `structured_data.insight` | A short summary of the interpretation. It can arrive as `null`, and some interpretations have no headline by design ([which one to show](/docs/guides/show-results/#what-to-show-first)). |
| `structured_data.headline` | One sentence that opens the interpretation. |
| `structured_data.sections[]` | The parts of the interpretation, each with `key`, `title`, `body` (Markdown) and `severity` (`info`, `watch`, `alert` or `null`). |
| `interpretation` | The whole interpretation as Markdown: the headline followed by the sections. |

An audience that does not resolve falls back to the default reading without an error: compare `audience_applied` with the one you asked for. With the SDK, the `audience.not-applied` warning says so; there is no route to list the audiences.

The `key` is the stable identity of a section (for example `reading`, `strength`, `risk`, `recommendation`); match sections by `key`, never by `title`. The `title` is written for the audience and can repeat: two sections with different keys can come with the same title.

`interpretation` and `sections` carry the same content ([show one of them](/docs/guides/show-results/#what-to-show-first)).

With the SDK in real time there is **one interpretation per session** since 0.38.0: the stored one, the same text your backend reads later with `POST /analyze` (`from_cache: true`). When you leave `triggerAnalysis` on, the `Final` makes Engine generate and store it; `stop()` waits for Engine's notice (`constellation.complete`) and, if it does not arrive in time, calls `POST /analyze` once, which serves the stored one. `SessionReport.interpretationSource` says where the one on the page came from (`'sse'`, `'analyze-cache'`, `'analyze-generated'`, `'analyze'` or `'stream'`); with `'analyze-generated'` (warning `analysis.regenerated`), `/analyze` had to generate a new one and the session may have been interpreted twice. Up to 0.37 the SDK also opened `/analyze/stream` in `stop()`, so there were **two interpretations** of one session, with different texts, both billed: see [two interpretations](/docs/resources/pitfalls/#pf-two-interpretations). `/analyze/stream` still generates a new interpretation on every call and Engine does not store it: whoever calls it directly over the HTTP API pays for a text the backend will not read later, and the SDK uses it only if you ask for `interpretation: 'stream'`.

How the analysis came out is `metadata.status`; the rest of `metadata` (model, token counts, ids, timings) is internal to Engine. This documentation does not promise those fields: do not build on them or show them to your users, because they can change or disappear without notice.

A Measurement capture has no interpretation, so do not call `POST /analyze` for it: if you do, Engine answers `409` with `reason: PROTOCOL_NOT_ANALYSED`, even before you capture. `POST /analyze/stream` and `GET /analyze/lite/{userProtocolId}/{protocolMechanicId}` answer the same.

```json
{
  "code": 409,
  "reason": "PROTOCOL_NOT_ANALYSED",
  "hint": "Its indicators are computed and available through GET /results. There is no narrative analysis for this protocol, and retrying will not produce one."
}
```

While Engine is analysing the session (normally the analysis it starts by itself after the capture, or one you forced with `reAnalyze`), `POST /analyze` does not start a second one: it answers `202` with `reason: ANALYSIS_IN_PROGRESS`, the `Retry-After` header and `retryAfterSeconds` in the body. Calls for a single `step` never get it, and the mark expires after 10 minutes.

```json
{
  "code": 202,
  "reason": "ANALYSIS_IN_PROGRESS",
  "message": "An analysis of this session is already running. Wait for constellation.complete on the stream, or call again later.",
  "retryAfterSeconds": 30
}
```

It is not an error: wait for `constellation.complete` on the stream, or call again after `retryAfterSeconds`. The SDK does not handle it yet: see [Errors](/docs/sdk/errors/#on-device) for what it does today.

When the interpretation service refuses the analysis, Engine answers with the same status (for example `422`) and a body with `code` and a generic `message`, without the service's internal detail; a `502` carries no internal text either. Today a `422` does not say whether the cause is the taxonomy or your organization's record: compare the taxonomy ids with the protocol's before recapturing, and if they match, ask Neurologyca.

### Preview fields

Some interpretations also bring these fields inside `structured_data`. They are **Preview**: until Neurologyca confirms them as part of the contract they can change or disappear, so read them only when they are there and keep your page working without them. So far they have only been seen in the test environment's Engine. As with `metadata`, rely only on what this table lists: the rest of `structured_data`, and of each pair, is not promised.

| Field | What it is |
| --- | --- |
| `structured_data.primary_emotion.term` | The main emotion of the session, as a catalogue term in English (for example `Determined`), whatever the language of the narrative. |
| `structured_data.selected_ehcis[]` | The indicators the context declares relevant for its reading, in the order the context declares them (not sorted by value), each with its `id` and `measured_value`: the value of the whole session, computed by Engine. The `id` is not the key in `/results` (`stress_intensity` here, `Stress_intens` in `aggResults`). To find its indicator, compare the `id` with the name or the key of each indicator in the table above, ignoring case and anything that is not a letter or a digit: `stress_intensity` matches Stress intensity, whose key is `Stress_intens`. Motivation and the four that need previous sessions also match: which ones to show, in [What to show first](/docs/guides/show-results/#what-to-show-first). |
| `structured_data.pairs[]` | How the steps go together as questions. Each pair brings `index`, `status` (`complete`; with a question in one step and its answer in the next, `incomplete` with the note `question_from_preceding_step` in `notes`, its question being the step before the closing, and the question step `unpaired`, without orders) and `windows.opening.order` and `windows.closing.order`: the step orders, the same keys as `aggResults`, where the question opens and where it closes. Ignore a pair whose orders are not in your results or whose `status` you do not know. |

To group the steps by question, with or without `pairs[]`: [Per step or per question](/docs/guides/show-results/#per-step-or-per-question).

### A 0 to 100 index

In some domains the interpretation service also computes **an index from 0 to 100** and publishes it inside `structured_data`, under its own key. Each domain that has one uses its own key with the same shape; `wellness_index` is one of them. You do not configure anything: it comes in the same `structured_data` you already read.

```json
{
  "wellness_index": {
    "value": 47,
    "band": "medium",
    "status": "degraded",
    "indicators_used": ["stress_intensity", "arousal", "valence", "workload"],
    "degraded_signals": ["tens"],
    "label": "<the sentence to show, in the language of the narrative>"
  }
}
```

| Field | What it is |
| --- | --- |
| `value` | An integer from 0 to 100, already rounded. Show it as it comes; never recompute it. `null` with `not_shown`. |
| `band` | The key of the range the value falls in. Each index defines its own; for `wellness_index` they are `low` (0 to 39), `medium` (40 to 59) and `high` (60 to 100). It is a key, not text to show: the sentence is `label`. `null` with `not_shown`. |
| `status` | `ok` (every indicator was there), `degraded` (one or more were missing and the value was computed with the rest: show it as a less reliable reading) or `not_shown` (too many were missing: show no number). |
| `indicators_used`, `degraded_signals` | Which indicators went into the value and which were missing. |
| `label` | The sentence to show next to the number, complete and in the language of the narrative, written by the interpretation service; with `degraded` it already says the reading is less reliable. Show it as it comes: do not compose, translate or extend it, and do not compare it in your tests, because its wording can change without a new SDK version. `null` with `not_shown`, and in interpretations stored before it existed. |

- **The narrative does not cite the number.** The interpretation's text never receives it; the sentence that goes with the number is `label`. When `label` is `null` and you want it, ask for a fresh interpretation from your backend (`reAnalyze`).
- **It is missing** from interpretations stored before the index existed (a `/analyze` that serves one, `from_cache: true`, comes without it; a `reAnalyze` brings it, unless Engine keeps the previous one, `re_analyze_kept_previous: true`), and from `GET /analyze/lite`, which does not compute it. Since the interpretation is stored per audience, one audience of a session can have it and another not.

With the SDK (0.39.0 or later; `label` since 0.40.0 and `capture-server` 0.17.0), `readScoreIndex(structured, key = 'wellness_index')`, in `@neurologyca/capture` (also `/helpers`) and in `@neurologyca/capture-server`, reads it and checks its shape: it returns `{ value, band, indicatorsUsed, degradedSignals, status, label }`, or `null` when the key is not there, when the interpretation predates it or when the shape does not fit (then the warning `score-index.malformed`). It never throws, and never rejects an index because of `label` (one that is not a string reads as `null`). Live, `structured` arrives in `onInterpretation`, in `onInterpretationDetails` and in `CaptureOutcome.structured` when `stop()` resolves (with `interpretation: 'stream'` it arrives in `onInterpretationDetails`, and `CaptureOutcome.structured` is `null` unless the fallback `/analyze` delivers it); in your backend, in `AnalyzeResult.structured` of `admin.analyze()`, the path of a deferred capture.

## Ask for a fresh interpretation

Engine stores the interpretation per session and audience. Once one exists and its analysis came out complete, `POST /analyze` returns it (`from_cache: true`, in under a second). With `metadata.status` `degraded` or `failed`, or none stored yet, every call regenerates it, which costs language-model tokens and time (generating an interpretation usually takes tens of seconds and can take about two minutes end to end). Ask once, never in a loop. To get a new one for the same session and audience, send `reAnalyze: true` from your backend:

```json
{ "userProtocolId": "<UP>", "protocolMechanicId": "<PM>", "reAnalyze": true }
```

- The answer carries `from_cache: false` and takes as long as a first interpretation (usually tens of seconds, up to about two minutes end to end). The new interpretation replaces the stored one: the next request without `reAnalyze` returns it, with `from_cache: true`.
- It only affects the audience you ask for, the `audience` of the request or the person's own: the stored interpretation of another audience stays as it was.
- If the new analysis fails or comes out worse, Engine keeps the stored one and returns it with `re_analyze_kept_previous: true`.
- The name is matched exactly: `REANALYZE` or `ReAnalyze` gets a `400` (`Unknown key 'REANALYZE': the field is 'reAnalyze', with that exact casing.`).
- **Every `reAnalyze` generates a new interpretation, which costs language-model tokens.** Send it on a deliberate decision, never in a loop or on every read. To compare two readings, look at `from_cache` first: with `true`, it is the same interpretation you already had.
- Only from your backend. The [proxy](/docs/api/proxy/) removes it from the browser's `/analyze` bodies, so a page cannot force it.

With the SDK, from your backend: `admin.analyze(pair, { reAnalyze: true })` of `createEngineAdmin` (`AnalyzeOptions.reAnalyze`). `AnalyzeResult.fromCache` is Engine's `from_cache` and `AnalyzeResult.keptPrevious` its `re_analyze_kept_previous`. `admin.analyzeForAudiences` never forces one: asking again for an audience returns the stored interpretation.

**Reading a session again later, without paying for another**: only a `complete` one, with the audience it was written for and without `reAnalyze` ([how](/docs/guides/show-results/#what-to-keep-and-how-to-read-again-without-paying)).

## What Engine does not return

No aggregate across a whole protocol, no webhooks and no audio.

## In the SDK

The SDK gives you the same results, already read: `stop()` resolves with a `CaptureOutcome` (`status`, `hcis`, `hcisByStep`, `frameCount`, `interpretation` and, since 0.39.0, `structured`):

```json
{
  "status": "complete",
  "hcis": {
    "valence": "<number>",
    "arousal": "<number>",
    "Confusion": "<number>",
    "Stress_intens": "<number>",
    "…": "65 signals in total; this example shows 4"
  },
  "hcisByStep": {
    "1": {
      "valence": "<number>",
      "arousal": "<number>",
      "Confusion": "<number>",
      "Stress_intens": "<number>",
      "…": "65 signals in total; this example shows 4"
    }
  },
  "frameCount": 450,
  "interpretation": null,
  "structured": null
}
```

The values come from a person's face, so here they go without them; the names are the public indicators you get, and the count is from a capture with Measurement later than the examples above.

During the capture, `onResult` brings a `ProtocolResultEvent`:

| Field | What it is |
| --- | --- |
| `ProtocolResultEvent.hcis` | The means of the indicators |
| `ProtocolResultEvent.hcisByStep` | The means, per step |
| `ProtocolResultEvent.frameCount` | The frames behind them |
| `ProtocolResultEvent.raw` | The whole body of `GET /results`: draw the per-frame series from it, with no extra call |

The scales are the ones above: 0 to 100, Valence from −100 to 100, Attention 0 or 1 per frame and its mean as the fraction of frames with attention. If you asked for an interpretation, `onInterpretationDetails` brings its structured details right after `onInterpretation`, with the same `structured` and `metadata` (since 0.38.0). Only with `interpretation: 'stream'` do they arrive later, normally after `stop()` has resolved: then wait for them with a deadline of your own.

How the capture went comes in the `SessionReport` that `onReport` receives when it ends. Since 0.43.0 (kodec 5.0.0-rc.14) two of its counters count differently: `codecErrors` no longer counts the face reload of `face.context-lost` and `prepare.face-lost`, nor a `capture-stalled` gap that falls within it, and still counts a lost camera (`track-ended`); `transcription.lostOnClose` also counts an utterance cut by an `abort()` or a `stop()` in the middle of a step, where before it could read `0`. Two warnings say what did not reach the result: `baseline.framesLost` (the server confirmed fewer baseline frames than were sent, and nothing retries them) and `audience.not-applied` (the interpretation came in the default reading). Every warning: [Errors, warnings and retries](/docs/sdk/errors/#warnings-worth-showing).
