# Show and use the results

What to show and do with each piece of the response; what each field is: [HCIs and results](/docs/concepts/results/).

## In short

- The indicators arrive first; an interpreted protocol then adds a written reading for an audience.
- Show the indicators first; the reading, unless it failed (with a notice if it is partial).
- The reading supports the person; never use it on its own to decide about them.
- Some pieces can be missing: Measurement is not interpreted, what the person said arrives only in the test environment's Engine today, and some fields are Preview.
- Build only on what is documented.

## What arrives, by which way and when

| What | SDK · in the page | SDK · in your backend | HTTP API · route |
| --- | --- | --- | --- |
| Indicators | `onResult` (`hcis`, `hcisByStep`, `frameCount`, `raw`); `CaptureOutcome` when `stop()` resolves | `getResults(pair)`, `getProtocolResults` | `GET /results/{userProtocolId}/{protocolMechanicId}` |
| `speech` | Only inside `raw` | `getResults().speech` (`null` without the block) | The same `GET /results` |
| Interpretation | `onInterpretation`, then `onInterpretationDetails`; `CaptureOutcome.interpretation` and `.structured` | Nothing live (the page sends you `metadata.status` and `audience_applied`); later, `admin.analyze` | `constellation.complete` on `GET /stream/{userProtocolId}`, then `POST /analyze` ([step 6](/docs/api/#6-wait-for-the-interpretation)) |
| Device report | `onReport` (`SessionReport`, also on `endedBy: 'abort'` or `'error'`; not in `CaptureOutcome`) | Nothing | Nothing |
| Deferred (Preview) | Nothing | After `succeeded`: `getResults`, and `admin.analyze` by `ProcessorInterpretation` | The same routes |

`onResult` comes before `stop()` resolves, which by default (`'engine'`) waits for the interpretation: draw the indicators from it ([The outcome](/docs/sdk/on-device/#the-outcome)). The SDK waits up to `analyzeTimeoutMs` ([Timeouts](/docs/guides/timeouts/#the-short-version)) and a deferred job 300 s by default ([The interpretation](/docs/sdk/processing/#the-interpretation)).

## What to show first

1. **The indicators, on arrival**: only the public ones that reach you ([they depend on your context](/docs/resources/pitfalls/#pf-hci-not-in-your-context)), by their key ([the table](/docs/concepts/results/#human-context-indicators)); never Motivation (`faa`, not valid); the four that need previous sessions, as locked.
2. **Then `metadata.status`**: `complete`; if the interpretation arrives `degraded`, with a notice; `failed` never as a result (`E_ANALYSIS_FAILED` in the page; `E_ENGINE_HTTP` from `admin.analyze`). The indicators still hold ([the pitfall](/docs/resources/pitfalls/#pf-interpretation-status)).
3. **The summary**: `structured_data.insight`, else `structured_data.headline`, else the first of `sections[]`.
4. **The reading, one of the two**: `sections[]` (by `key`, never by `title`) or the Markdown of `interpretation`, rendered without raw HTML.
5. **A 0 to 100 index**, if the domain has one: `readScoreIndex` on `structured`; `value` and `label` as they come, no number with `status: 'not_shown'`, `degraded` as less reliable.
6. **Who it was written for**: `audience_applied` (in the backend, `AnalyzeResult.audienceEvidence.audienceApplied`), else «default reading»; an echo, not proof.
7. **The Preview fields**, only if they arrive: `primary_emotion.term` (an English catalogue term); `selected_ehcis[]` first among the indicators, public ones only (a Relevant one may not be in your `/results`), never Motivation (`faa`) nor the four that need previous sessions, matched by [the rule](/docs/concepts/results/#preview-fields); `pairs[]`, below.

Their shape:

```json at="body.structured_data"
{
  "insight": null,
  "primary_emotion": { "term": "<text>" },
  "selected_ehcis": [{ "id": "coherence", "measured_value": "<number>" }]
}
```

### Only what is documented

The response carries more fields than documented, [Preview fields](/docs/concepts/results/#preview-fields) aside, and more of `metadata` than `status`: they are not promised and can change; do not build on them or show them.

## What arrives and what does not

If a field is missing, show the last column.

| Field | When it arrives | When it does not | What to show instead |
| --- | --- | --- | --- |
| Indicators, per step and per frame | When the capture is complete, in every mode. | Before that (`rawResults: {}`); keys your context does not include; Workload and Motivation in their warm-up (`null`); four never arrive. | Read again later; a missing key is a gap, not zero; the four, locked. |
| `speech.questionText` | In the question's step, in the narrative's language; it does not depend on your context's indicators. | A person without a narrative language; a step without a question; outside the test environment's Engine (`speech: null`); the interruption route. | The question you showed, in the spoken language. |
| `speech.transcript` | In the step where it was said, as your app sent it; only in the test environment's Engine. | See [The transcript](/docs/guides/show-results/#the-transcript). | Why there is nothing, never an empty box. |
| `metadata.status` | `complete`, `degraded` or `failed`; in deferred, first the job's `interpretation` (`ready`, `degraded`, `failed`, `timeout`, `unknown`, `not-requested`). | Measurement or `triggerAnalysis` off (`results.ready` says why in `reason`: `protocol_not_interpreted` or `analysis_not_requested`), or Engine skipped it (an answer step without speech: `not-requested`). | The indicators only. |
| `insight`, `headline`, `sections[]` | In the interpretation. | `insight` can be `null`, some have no `headline`; `CaptureOutcome.structured` is `null` with `interpretation: 'stream'`; `202 ANALYSIS_IN_PROGRESS`; `E_INTERPRETATION_TIMEOUT`. | The summary, as above; on `202`, wait (`constellation.complete` or `retryAfterSeconds`); on a timeout, the indicators, then read it once from your backend. |
| `audience_applied` | At the root of `/analyze`: the effective audience (the one requested or else the person's); live, in the event's `raw` if Engine sends it. | `null` with neither (none requested, none on the person); absent from the page's event if Engine does not send it. | The audience you set on the person, or «default reading». |
| A 0 to 100 index | Only in domains that publish one (`wellness_index` is one), each under its own key, with `readScoreIndex`. | Other domains; interpretations stored before it (`from_cache: true`); `GET /analyze/lite`; `status: 'not_shown'`. | No number. |
| `primary_emotion.term` · Preview | In some interpretations, an English catalogue term; seen so far only in the test environment's Engine. | In the rest; it can change or go away. | Nothing: the page works without it. |
| `selected_ehcis[]` · Preview | In some interpretations, in the context's order, each `id` with `measured_value` (the whole session). | In the rest; ids that are not public indicators, Motivation or the four that need previous sessions. | Your own choice of public indicators, without those. |
| `pairs[]` · Preview | In some interpretations: `index`, `status` and the orders of `windows.opening` and `windows.closing`. | In the rest; a pair that is not `complete` or whose orders are not in your results. | Group from `speech` (next section). |

`session.effective_active_attention` can arrive `null` right after the Final: read `/results` again ([`session`](/docs/concepts/results/#session)).

Why no interpretation in Measurement? Its kit sets `triggerAnalysis: false` and `/analyze` answers `409 PROTOCOL_NOT_ANALYSED` ([Measurement](/docs/guides/measurement/)).

## Per step or per question

How do I group the steps by question? The indicators and `speech` come per step; a question can span two steps (the answer in the `media_from: previous_step` one). The playground groups them as the code below does: first by `pairs[]` (`complete`, or `incomplete` noted `question_from_preceding_step`: the question is the step before); the steps no pair covers, by `speech` (a step with `questionText` takes the next step, n+1, as its answer if that one only has `transcript` or repeats the question). With pairs but no `speech`, the roles are opening and closing, not question and answer.

`pairs[]` is Preview and `speech` only in the test environment's Engine: the page has to work per step without them. Their shape: [`speech`](/docs/concepts/results/#speech) and [`pairs[]`](/docs/concepts/results/#preview-fields).

```js
// Groups one session's steps by question. pairs: structured_data.pairs of POST /analyze
// (Preview); speech: from GET /results; orders: the steps read, e.g.
// Object.keys(aggResults). Each group: steps (order and role: question, answer, opening,
// closing or single), questionText, transcript and answerOrder (the answer's step).
export function groupByQuestion({ pairs = [], speech = null, orders }) {
  orders = orders.map(Number)
  const ok = (x) => Number.isInteger(x) && x >= 1
  const have = new Set(orders), used = new Set(), out = []
  const sp = (o) => speech?.[String(o)] ?? {}
  const st = (order, role) => ({ order, role })
  const add = (steps, questionText, transcript, answerOrder) =>
    out.push({ steps, questionText, transcript, answerOrder })
  for (const p of Array.isArray(pairs) ? pairs : []) {
    const c = p?.windows?.closing?.order
    const prev = p?.status === 'incomplete' && ok(c) && c > 1 &&
      Array.isArray(p.notes) && p.notes.includes('question_from_preceding_step')
    const o = prev ? c - 1 : p?.windows?.opening?.order
    if (!ok(p?.index) || (!prev && p.status !== 'complete')) continue
    if (!ok(o) || !ok(c) || o > c) continue
    if (!have.has(o) || !have.has(c) || used.has(o) || used.has(c)) continue
    used.add(o); used.add(c)
    const roles = speech ? ['question', 'answer'] : ['opening', 'closing']
    add([st(o, roles[0]), st(c, roles[1])],
      sp(o).questionText ?? null, sp(c).transcript ?? null, c)
  }
  const rest = speech ? orders.filter((o) => !used.has(o)).sort((a, b) => a - b) : []
  for (let k = 0; k < rest.length; k++) {
    const o = rest[k], next = rest[k + 1], q = sp(o).questionText, t = sp(o).transcript
    if (q && (t || orders.length === 1)) add([st(o, 'single')], q, t ?? null, o)
    else if (q && next === o + 1 && ((sp(next).transcript && !sp(next).questionText) ||
        sp(next).questionText === q)) {
      add([st(o, 'question'), st(next, 'answer')], q, sp(next).transcript ?? null, next)
      k++
    } else if (q) add([st(o, 'question')], q, null, null)
    else if (t) add([st(o, 'answer')], null, t, o)
  }
  out.sort((a, b) => a.steps[0].order - b.steps[0].order)
  return out.map((g, i) => ({ n: i + 1, ...g }))
}
```

## The transcript

Where is the transcript of what the person said? In the field `speech["n"].transcript` of `/results`: per step, what your app sent, only in the test environment's Engine today: elsewhere `getResults` gives `speech: null`; `{}` means no step had a question or a transcript. Joined, the steps are not the full text ([the pitfall](/docs/resources/pitfalls/#pf-transcripts-not-full-text)).

Why does a step bring the question but not what was said?

- HTTP API: nothing transcribes; your backend sends `sttByStep` ([Send the transcript](/docs/api/#send-the-transcript)).
- Transcription off: `transcribe: false`, no `transcribe` in kit or code, or `transcribeSteps` leaves out the step's type.
- The device cannot: [the `stt` warning](/docs/guides/csp-transcription/#when-the-device-cannot-transcribe) and its `blocker`.
- The CSP blocks the speech worker (`workerBlockedByCsp`).
- Silence: the step in `transcription.stepsTranscription` of `onReport` has `transcribed: false` or `emitted: 0`.
- Wrong spoken language: translated or empty, not absent ([the pitfall](/docs/resources/pitfalls/#pf-transcription-wrong-language)).
- Speech outside every step; a deferred job without transcription.

The transcript belongs to the person: show it only to them (or to whom your consent says), never in logs, analytics or fixtures ([Privacy](/docs/resources/privacy/)).

## What to keep and how to read again without paying

Keep with your user: the pair (`userProtocolId`, `protocolMechanicId`) and your opaque `externalId`, never the email ([Keep the pair](/docs/sdk/results-backend/#keep-the-pair)); the person's audience (or none) and the declared spoken language; and `metadata.status` and `audience_applied` (live, your page sends them; from your backend, in `AnalyzeResult`). Engine keeps results until `DELETE /users/{externalId}`.

Read an interpretation again without paying, from your backend: `admin.analyze(pair, { audience })` only if the stored one came out `complete`, with its `audience_applied` (or, if it did not arrive, the audience you set on the person), without `reAnalyze`: `from_cache: true`; over HTTP, `POST /analyze` with `audience` and without `reAnalyze`. Without `audience`, Engine uses the person's current one and, if it changed, generates and bills another; with `audience_applied` `null`, omit `audience` only while the person still has none. `degraded` or `failed`: every call regenerates it, so once, never in a loop.

- `fromCache: null` means Engine did not send the flag (`/analyze/lite` and `/analyze/stream` never), not «freshly generated».
- `client.analyze` takes no `audience`: read again from your backend. A `202` gives `interpretation: null` and `inProgress: true`: «interpreting» ([retry](/docs/sdk/errors/#the-202-of-the-interpretation)).
- `reAnalyze` only on a decision, from your backend: each one is billed ([Ask for a fresh interpretation](/docs/concepts/results/#ask-for-a-fresh-interpretation)).

## What you can build

- A series per step from `rawResults`, inside the `raw` of `onResult`, sorted by `timestamp`, gaps where a key is missing.
- Another audience for the same session, without measuring again (`admin.analyze(pair, { audience: 'other' })` or `analyzeForAudiences`): each audience's first request bills a whole interpretation, and an unknown label is accepted without error and billed ([the pitfall](/docs/resources/pitfalls/#pf-audience-unvalidated)).
- Nothing on the four that need previous sessions (no route returns them; locked at most, [why](/docs/concepts/results/#indicators-that-need-previous-sessions)) or on [what Engine does not give](/docs/concepts/results/#what-engine-does-not-return).

> **Responsible use**
>
> - The reading is meant to support the person and must never be used on its own to decide about them.
> - It does not diagnose, does not detect lies, and does not compare or classify people.
> - Your app informs the person and collects their consent.

> [Measure](/playground#measure) shows the whole response and [Results](/playground#results) (signed in) the view by range ([The playground in DevLab](/docs/start/testing/#the-playground-in-devlab)).
