# Measurement only

## What you get

**Measurement** is a context without a taxonomy: you send capture data and get the [indicators](/docs/concepts/results/) back, per frame and aggregated, with no interpretation. It is the path of the [quickstart](/docs/start/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](/docs/start/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](/docs/start/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:

### SDK

```js
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](/docs/start/quickstart/) and [On-device (real time)](/docs/sdk/on-device/).

### HTTP

Over the HTTP API, send the frames yourself; the [Quickstart](/docs/start/quickstart/) runs it with cURL.

## The Measurement protocol

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

| Position | When | Mechanic | Steps |
| --- | --- | --- | --- |
| 1 | Any time | Measurement | measurement_free (min 6 s · no max) |

## One measurement, one enrolment

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:

### cURL

```bash
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

```js
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

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

## How long to capture

- 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](/docs/sdk/steps/).
- 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.

## Read the indicators

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](/docs/concepts/results/#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](/playground#flow).

## No interpretation

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`](/docs/concepts/results/#speech), only in the test environment's Engine). Otherwise, turn transcription on only in protocols with speech steps ([On-device (real time)](/docs/sdk/on-device/#transcription)).

## Baseline

A baseline is recommended to compare people or sessions, not required: the enrolment answers with `baselineWarning` and goes on. See [Baseline](/docs/concepts/baseline/).

## What is not there yet

- 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)](/docs/sdk/deferred/)).
- 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](/docs/sdk/backend/#people-and-enrolments-createengineadmin)). `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`.
