HCIs and results
What a Human Context Indicator is, the shape of the results, the live events, and the interpretation for an audience.
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.
Human Context Indicators
Section titled “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); an indicator that arrives in an example and not in your capture is this pitfall. 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.
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
Section titled “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
Section titled “The shape of the results”GET /results/{userProtocolId}/{protocolMechanicId} returns, per step:
{ "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,
rawResultsandaggResultscome back empty: poll. GET /results/{userProtocolId}returns every position as{ userProtocolId, mechanics[] }: one item per mechanic, each with its ownrawResults,aggResultsandspeech.…/{stepOrder}returns a single step, with itsstepOrder.- 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). 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.
Before the capture completes:
{ "rawResults": {}, "aggResults": {} }speech
Section titled “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:
{ "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 hasquestionTextortranscript, never""ornull; with nothing to show,speechis{}. questionTextis 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 noquestionText.transcriptis the speech your app sent for that step (sttByStep, see Send the transcript), stored as sent. Speech that could not be placed in a step is not here, so joining thetranscriptvalues 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),questionTextarrives in the question’s step andtranscriptin 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
Section titled “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[].
{ "session": { "effective_active_attention": { "v": 83.33, "n": 1247 } } }vgoes from 0 to 100: the percentage of the session’s measured frames withAttention = 1, and it is not the 0 to 1 mean ofaggResults.mean.Attention.nis 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.
nullmeans it was not measured (which is not 0) or that your context does not include it. On the interruption route it isnull.- It can also arrive
nullin the read right after the Final, even when it was measured (seen in the test environment’s Engine, by the SDK path): read/resultsagain a little later before showing it as missing.
Means across steps
Section titled “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[], with an interpretation) and 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
Section titled “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.
Live events
Section titled “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). Never treat it as the interpretation.
Interpretation for an audience
Section titled “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.
| 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). |
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).
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. /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.
{ "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.
{ "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 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
Section titled “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. |
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.
A 0 to 100 index
Section titled “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.
{ "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. Whenlabelisnulland you want it, ask for a fresh interpretation from your backend (reAnalyze). - It is missing from interpretations stored before the index existed (a
/analyzethat serves one,from_cache: true, comes without it; areAnalyzebrings it, unless Engine keeps the previous one,re_analyze_kept_previous: true), and fromGET /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
Section titled “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:
{ "userProtocolId": "<UP>", "protocolMechanicId": "<PM>", "reAnalyze": true }- The answer carries
from_cache: falseand 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 withoutreAnalyzereturns it, withfrom_cache: true. - It only affects the audience you ask for, the
audienceof 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:
REANALYZEorReAnalyzegets a400(Unknown key 'REANALYZE': the field is 'reAnalyze', with that exact casing.). - Every
reAnalyzegenerates 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 atfrom_cachefirst: withtrue, it is the same interpretation you already had. - Only from your backend. The proxy removes it from the browser’s
/analyzebodies, 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).
What Engine does not return
Section titled “What Engine does not return”No aggregate across a whole protocol, no webhooks and no audio.
In the SDK
Section titled “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):
{ "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.