---
title: "Run Expert Batch"
method: POST
path: "/v2/insights/expert/{skill}/batch"
---

# Run Expert Batch

`POST /v2/insights/expert/{skill}/batch`

## Request

- Base URL: `https://api.imentiv.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.imentiv.ai/v2/insights/expert/{skill}/batch`
- Auth: OAuth 2
  - Authorization code: `https://api.imentiv.ai/oauth/authorize`
  - Token URL: `https://api.imentiv.ai/oauth/token` scopes: `insights.write`, `media.read`

Run one expert skill on up to ten windows of recordings the user may read, at once.

Takes a user's delegated access token with the `insights.write` scope, like a single
call (readable recordings and billing as there); an API key or a browser session is
refused with 403.

Each item takes the fields of a single call, including its own `media_binding`, except
`product`, `language` and `condition`, which the batch shares (recordings in different
languages belong in separate batches). A batch reads at most four distinct recordings
(422 `invalid_request` on `items` beyond that). Every recording must be readable by the
token's user before any is evaluated: one that is missing or not readable by them is a 404
`binding_not_found` for the whole request, and a token without `media.read` is a 403
naming the scope; nothing is evaluated or billed then.

The items run concurrently; the entries come back in request order, each naming its
`media_binding` and carrying its own `result` or `error`, charge, `replayed` flag and
`model_ids`, and `credits_charged` is their sum. A problem with the request as a whole
(validation, authentication, a recording that is not readable) is the usual error response;
a failure of one item is that
entry's `error`, e.g. `evaluate_timeout`, `expert_in_progress`, `media_not_ready` or
`moments_not_ready` for an item whose recording is still being processed (its `field` names
`items.{i}.media_binding`, and the items on other recordings still run), or a subject,
person or moment of that item the recording does not have (`subject_required`,
`moment_not_found`, `invalid_request` naming the item's field), with the same fields a single call's error
carries. A failed item is not charged and its siblings still run. If the balance cannot
cover the items that need a new evaluation, those items answer `insufficient_credits`
together; replays and requests outside the skills' scope are still answered. Identical
items are evaluated once and charged once: the first carries the charge, the others
are `replayed`.

## Path parameters

- `skill` 'interpret_window' | 'assess_response' | 'explain_moment' | 'compare' | 'narrate', required

## Request body

- ExpertBatchRequest: Up to ten calls of one skill, each on one of the caller's own recordings. The calls may read several recordings (at most four distinct ones in a batch); `product`, `language` and `condition` are shared, so recordings in different languages belong in separate batches.
  - `product` string, required: The calling application's tag, recorded for usage reporting only.
  - `language` string, nullable: The spoken language, when known. It can only lower a reading's confidence.
  - `condition` string: The recording condition: `default`, `in_cabin_ir`, `off_axis_gt30` or `road_noise`. A condition other than `default` can only lower a reading's confidence.
  - `items` ExpertBatchItem[], required
    - `window` WindowIn, required: A half-open window `[start_ms, end_ms)` on the bound media's clock.
      - `start_ms` integer, required
      - `end_ms` integer, required
    - `modalities` string[]: The modalities to read, each at most once.
    - `situation` SituationIn[]
      - `type` string, required: Section type chosen by the application.
      - `text` string, required
    - `question` string, nullable: `interpret_window` only: what to interpret the window for.
    - `stimulus` StimulusIn: What the subject may have responded to, on the recording's clock.
      - `onset_ms` integer, required: When the stimulus began. Must be inside `window`.
      - `end_ms` integer, nullable: When it ended, if known.
      - `label` string, nullable: A short name for the stimulus.
    - `baseline` WindowIn: A half-open window `[start_ms, end_ms)` on the bound media's clock.
      - `start_ms` integer, required
      - `end_ms` integer, required
    - `moment_id` string, nullable: `explain_moment` only, and required there: a moment of the chosen face in `window`.
    - `people` object, nullable: `compare` only, and required there: two to four people, each a label mapped to one subject id per requested modality. Replaces the binding's `subjects`.
    - `focus` string, nullable: `narrate` only: what to narrate for.
    - `media_binding` ExpertMediaBindingIn, required: One of the caller's own processed recordings, with at most one subject per modality.
      - `media_id` string, required
      - `media_type` 'video' | 'audio', required
      - `subjects` object, nullable: Per modality, the one subject id to read. Required for a requested modality with more than one subject in the recording; a modality with exactly one is chosen automatically.

## Response `200`

Successful Response

- ExpertBatchResponse
  - `skill` 'interpret_window' | 'assess_response' | 'explain_moment' | 'compare' | 'narrate', required
  - `credits_charged` integer, required: The sum over the entries.
  - `entries` ExpertBatchEntry[], required: One per item, in request order.
    - `index` integer, required: The item's position in the request.
    - `media_binding` ExpertMediaBindingEcho, required: The recording an entry read.
      - `media_id` string, required
      - `media_type` 'video' | 'audio', required
    - `result` ExpertResult: One skill result. Anything but `ok` carries no findings.
      - `skill` 'interpret_window' | 'assess_response' | 'explain_moment' | 'compare' | 'narrate', required
      - `status` 'ok' | 'insufficient_evidence' | 'out_of_scope', required: `insufficient_evidence` when coverage, grounding or calibration cannot support a finding; `out_of_scope` when the question or focus is not about observed emotion.
      - `expert_version` string, required
      - `reason` string, required
      - `evidence_quality` string[]: Stable codes describing the evidence, e.g. `untested_modality:face` or `low_confidence_language:de`.
      - `quality_notes` ExpertClaim[]
        - `text` string, required
        - `citations` ExpertCitation[]
          - `id` string, required: A window of evidence (`w:...`) or a moment (`m:...`).
          - `modality` 'face' | 'voice' | 'text', required
          - `subject` string, required: The person the evidence belongs to.
          - `start_ms` integer, required
          - `end_ms` integer, required
      - `confounds` ExpertClaim[]
        - `text` string, required
        - `citations` ExpertCitation[]
          - `id` string, required: A window of evidence (`w:...`) or a moment (`m:...`).
          - `modality` 'face' | 'voice' | 'text', required
          - `subject` string, required: The person the evidence belongs to.
          - `start_ms` integer, required
          - `end_ms` integer, required
      - `alternatives` ExpertClaim[]
        - `text` string, required
        - `citations` ExpertCitation[]
          - `id` string, required: A window of evidence (`w:...`) or a moment (`m:...`).
          - `modality` 'face' | 'voice' | 'text', required
          - `subject` string, required: The person the evidence belongs to.
          - `start_ms` integer, required
          - `end_ms` integer, required
      - `citations` ExpertCitation[]
        - `id` string, required: A window of evidence (`w:...`) or a moment (`m:...`).
        - `modality` 'face' | 'voice' | 'text', required
        - `subject` string, required: The person the evidence belongs to.
        - `start_ms` integer, required
        - `end_ms` integer, required
      - `readings` ExpertReading[]
        - `state` string, required
        - `confidence` 'low' | 'medium' | 'high', required: Capped by how reliable the emotion models are for this state.
        - `supporting_modalities` string[], required
        - `citations` ExpertCitation[], required
          - `id` string, required: A window of evidence (`w:...`) or a moment (`m:...`).
          - `modality` 'face' | 'voice' | 'text', required
          - `subject` string, required: The person the evidence belongs to.
          - `start_ms` integer, required
          - `end_ms` integer, required
        - `note` string, required
      - `verdict` 'response' | 'no_response', nullable
      - `direction` string, nullable
      - `magnitude` 'low' | 'medium' | 'high', nullable
      - `onset_ms` integer, nullable
      - `below_engine_threshold` boolean, nullable
      - `baseline_used` ExpertWindow
        - `start_ms` integer, required
        - `end_ms` integer, required
      - `threshold_reference` string, nullable
      - `drivers` string[]
      - `robustness` ExpertClaim[]
        - `text` string, required
        - `citations` ExpertCitation[]
          - `id` string, required: A window of evidence (`w:...`) or a moment (`m:...`).
          - `modality` 'face' | 'voice' | 'text', required
          - `subject` string, required: The person the evidence belongs to.
          - `start_ms` integer, required
          - `end_ms` integer, required
      - `counterevidence` string[]
      - `contrasts` ExpertReading[]
        - `state` string, required
        - `confidence` 'low' | 'medium' | 'high', required: Capped by how reliable the emotion models are for this state.
        - `supporting_modalities` string[], required
        - `citations` ExpertCitation[], required
          - `id` string, required: A window of evidence (`w:...`) or a moment (`m:...`).
          - `modality` 'face' | 'voice' | 'text', required
          - `subject` string, required: The person the evidence belongs to.
          - `start_ms` integer, required
          - `end_ms` integer, required
        - `note` string, required
      - `arc` ExpertArcStep[]
        - `window` ExpertWindow, required
          - `start_ms` integer, required
          - `end_ms` integer, required
        - `reading` ExpertReading, required: One observed emotional state, with its confidence after calibration.
          - `state` string, required
          - `confidence` 'low' | 'medium' | 'high', required: Capped by how reliable the emotion models are for this state.
          - `supporting_modalities` string[], required
          - `citations` ExpertCitation[], required
            - `id` string, required: A window of evidence (`w:...`) or a moment (`m:...`).
            - `modality` 'face' | 'voice' | 'text', required
            - `subject` string, required: The person the evidence belongs to.
            - `start_ms` integer, required
            - `end_ms` integer, required
          - `note` string, required
    - `error` ExpertError: One item's error: the same object a single call returns as its error `detail`, including that code's fields (e.g. `retry_after_s` of `expert_in_progress`, `balance` and `required` of `insufficient_credits`, `field` of `invalid_request`).
      - `code` string, required
      - `message` string, required
    - `credits_charged` integer
    - `replayed` boolean
    - `model_ids` object, nullable: Per modality, the emotion model version the readings were calibrated against; null when the recording does not name one, and that modality is then reported as untested. Null when the item's recording could not be read.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-07** `45bdd041d683`: 3 breaking, 1 warning, 3 info
  - added the new required request property `items/items/media_binding`
  - removed the required property `expert_version` from the response with the `200` status
  - removed the required property `model_ids` from the response with the `200` status
  - removed the request property `media_binding`
  - …3 more
- **2026-10-01** `72330e2229c7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/changes/v2/insights/expert/:skill/batch/post.md)

---

[API](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai.md) - [All operations](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/llms.txt) - [OpenAPI document](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/revisions/bc15cec7e794?raw)