Skip to content
DevLab

Measurement only

Send capture data and get Human Context Indicators back, without interpretation.

On this page
  1. What you get
  2. The Measurement protocol
  3. One measurement, one enrolment
  4. How long to capture
  5. Read the indicators
  6. No interpretation
  7. Baseline
  8. What is not there yet

Measurement is a context without a taxonomy: you send capture data and get the indicators back, per frame and aggregated, with no interpretation. It is the path of the quickstart, which runs it end to end with the SDK, cURL or Python.

Measurement is a universal protocol in the test environment: every organization has it, with no assignment to ask for. The production Engine does not offer it yet (Your environments). Look for the Measurement protocol in GET /catalog/protocols. It comes with interpreted: false, like every protocol that is measured but never interpreted. If it is not in your list, your environment does not offer it yet (Your environments).

triggerAnalysis is two different things, and Measurement treats them differently. In the SDK it is an option of captureProtocol (true by default): the SDK asks for the interpretation, and for Measurement Engine refuses it with a 409. Over HTTP it is a field of the Final batch (absent means false): Engine ignores it with Measurement. Nothing is renamed: with the SDK pass triggerAnalysis: false, over HTTP you can leave it out.

With the SDK, two parameters make it work today:

JavaScript
import { createProtocolClient } from '@neurologyca/capture'
const client = createProtocolClient({ baseUrl: '/engine', taxonomy: { contextId: 'measurement' } })
const session = await client.captureProtocol({ userProtocolId, protocolMechanicId, source: { type: 'webcam' }, triggerAnalysis: false })

taxonomy: { contextId: 'measurement' } (Measurement has no taxonomy, so any value works) and triggerAnalysis: false (there is nothing to interpret). Since 0.29.0, the SDK decides it on its own when Engine says the protocol is not interpreted (interpreted: false): it sends no taxonomy, asks for no analysis even if you pass triggerAnalysis: true, and warns protocol.not-interpreted once. The test environment’s Engine returns interpreted; keep triggerAnalysis: false for Measurement anyway, which keeps it working with an Engine that does not say so: without it, the SDK asks for an analysis that Engine refuses with 409 PROTOCOL_NOT_ANALYSED, and since 0.29.0 that still ends complete. The contextId is still required in the configuration, though Measurement does not send it. The full loop: Quickstart and On-device (real time).

Over the HTTP API, send the frames yourself; the Quickstart runs it with cURL.

One position, one mechanic and one step of type measurement_free, with a minimum of 6 seconds and no maximum:

Each measurement is one enrolment and one capture. A position with a completed capture cannot be captured again:

JSON
{
"status": 409,
"body": {
"code": 409,
"reason": "POSITION_ALREADY_COMPLETED",
"message": "This mechanic already has a completed session."
}
}

To measure the same person again, enrol them again in the same protocol:

Shell
UP=$(curl -s -X POST "$ENGINE/user-protocols" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d "{\"user\":\"$EXT\",\"protocol\":\"$PROTOCOL\"}" | jq -r .userProtocolId)
JavaScript
const res = await fetch(`${ENGINE_BASE}/user-protocols`, {
method: "POST",
headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
body: JSON.stringify({ user: EXT, protocol: PROTOCOL }),
});
const { userProtocolId } = await res.json();
Python
res = requests.post(
f"{ENGINE_BASE}/user-protocols",
headers={"Authorization": f"Bearer {TOKEN}"},
json={"user": EXT, "protocol": PROTOCOL},
)
up = res.json()["userProtocolId"]

GET /users/{app_user}/user-protocols lists a person’s enrolments, so you can find their earlier measurements.

  • The catalogue declares at least 6 seconds. Engine does not enforce durations. The SDK warns by default (step.duration-below-min) and, with stepDurations: 'enforce', refuses (E_STEP_DURATION): see Steps and marking.
  • Some indicators need a window of signal: they appear only after about 5 seconds, and from then on they arrive in windows, not in every frame (about one frame in six at 30 frames per second). Which frame comes first changes from run to run, so never wait for a fixed frame number. In the quickstart sample, workload is in only a few of the 300 frames:
JSON
{ "framesWithWorkload": 21, "framesTotal": 300 }
  • Long captures take longer to close: 128 seconds were measured for a step of 5,888 frames. Poll with patience in proportion.

When the capture of the position is complete, the stream sends results.ready: with reason: analysis_not_requested when no batch asked for an interpretation, and with protocol_not_interpreted if the Final batch sent triggerAnalysis (see Live events). Use it as the signal, and keep polling GET /results/{userProtocolId}/{protocolMechanicId} until step 1 has entries as the fallback, as in step 6 of the quickstart. aggResults holds the mean of each indicator for the step and rawResults the value per frame. See it in the playground.

Measurement has no interpretation, so do not call POST /analyze in a Measurement flow. If it is called, Engine answers 409 with reason: PROTOCOL_NOT_ANALYSED, before or after capturing:

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."
}

Engine ignores triggerAnalysis with Measurement: there is no interpretation to start. If you send it on the Final batch, the capture completes with the same indicators and the stream sends results.ready:

JSON
{
"events": [
"connected",
"results.ready"
],
"resultsReady": [
{
"stepOrder": 1,
"analysis": false,
"reason": "protocol_not_interpreted"
}
]
}

Without triggerAnalysis, the same capture ends with analysis_not_requested:

JSON
{
"events": [
"connected",
"hci.warning",
"results.ready"
],
"resultsReady": [
{
"stepOrder": 1,
"analysis": false,
"reason": "analysis_not_requested"
}
]
}

Transcription is off by default in Measurement: its only step (measurement_free) is not a speech step. If the person talks and you transcribe, Engine keeps the text and /results returns it as the transcript of step 1 in speech (measured on 2026-11-02; speech, only in the test environment’s Engine). Otherwise, turn transcription on only in protocols with speech steps (On-device (real time)).

A baseline is recommended to compare people or sessions, not required: the enrolment answers with baselineWarning and goes on. See Baseline.

  • In deferred, Measurement works since 0.27.0: triggerAnalysis: false travels in the manifest and the processing service does not call /analyze. Since 0.29.0, when Engine says interpreted: false, the recording client writes it in the manifest too (interpreted: false, always with triggerAnalysis: false). Today you can record, upload and process with Neurologyca’s processing service, with nothing to deploy (Deferred (server-side)).
  • A kit built in your backend: since capture-server 0.20.0, buildTenantKit gives Measurement its own kit, kind: 'measurement', with taxonomy.contextId: 'measurement' and a notice to capture with triggerAnalysis: false; branch on kit.kind and resolve it before admin.enrol (Your backend). ProtocolSummary.interpreted says whether a protocol is interpreted (false for Measurement). What is not there: an Engine whose catalogue does not publish interpreted still makes buildTenantKit throw E_KIT_NO_CONTEXT for Measurement, as capture-server 0.19.0 and earlier always do. There, use the Measurement kit of the console (Your integration › Protocols › a protocol › Kit): its neuro.config.json carries taxonomy.contextId: 'measurement' and triggerAnalysis: false.