Skip to content
DevLab

Show and use the results

What to show first when the indicators and the interpretation arrive, what arrives in each case, where the transcript is, what to keep and how to read again without paying.

On this page
  1. In short
  2. What arrives, by which way and when
  3. What to show first
  4. Only what is documented
  5. What arrives and what does not
  6. Per step or per question
  7. The transcript
  8. What to keep and how to read again without paying
  9. What you can build

What to show and do with each piece of the response; what each field is: HCIs and results.

  • 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 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)
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). The SDK waits up to analyzeTimeoutMs (Timeouts) and a deferred job 300 s by default (The interpretation).

  1. The indicators, on arrival: only the public ones that reach you (they depend on your context), by their key (the table); 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).
  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; pairs[], below.

Their shape:

JSON
{
"insight": null,
"primary_emotion": { "term": "<text>" },
"selected_ehcis": [{ "id": "coherence", "measured_value": "<number>" }]
}

The response carries more fields than documented, Preview fields aside, and more of metadata than status: they are not promised and can change; do not build on them or show them.

If a field is missing, show the last column.

What arrives and what does not, field by field
FieldWhen it arrivesWhen it does notWhat to show instead
Indicators, per step and per frameWhen 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.questionTextIn 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.transcriptIn the step where it was said, as your app sent it; only in the test environment's Engine.See The transcript.Why there is nothing, never an empty box.
metadata.statuscomplete, 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_appliedAt 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 indexOnly 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 PreviewIn 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[] PreviewIn 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[] PreviewIn 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).

Why no interpretation in Measurement? Its kit sets triggerAnalysis: false and /analyze answers 409 PROTOCOL_NOT_ANALYSED (Measurement).

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 and pairs[].

JavaScript
// 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 }))
}

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).

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

  • HTTP API: nothing transcribes; your backend sends sttByStep (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 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).
  • 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).

What to keep and how to read again without paying

Section titled “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); 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).
  • reAnalyze only on a decision, from your backend: each one is billed (Ask for a fresh interpretation).
  • 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).
  • Nothing on the four that need previous sessions (no route returns them; locked at most, why) or on what Engine does not give.