--- title: "Evaluate Conversation" method: POST path: "/v2/insights/conversations/{conversation_id}/evaluate" --- # Evaluate Conversation `POST /v2/insights/conversations/{conversation_id}/evaluate` ## 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/conversations/{conversation_id}/evaluate` - Auth: one of: - API key in header `X-API-Key` - HTTP bearer - OAuth 2 - Authorization code: `https://api.imentiv.ai/oauth/authorize` - Token URL: `https://api.imentiv.ai/oauth/token` scopes: `insights.write`, `media.read` Evaluate one turn and return an output object valid against the conversation's schema. Synchronous. Live and unbound conversations answer within a short deadline suited to live use, or fail with 504 `evaluate_timeout`; a recording-bound conversation has a longer one, since a recording's evidence may have to be loaded first. For a bound conversation send `window` (milliseconds on the session or recording clock) and the `modalities` to read; `evidence_pending` says the live window was still filling. A `turn_key` is charged at most once. Repeating a finished turn replays its output free of charge in a `session` conversation (409 `turn_key_conflict` if the request differs) and is refused with 409 `turn_key_used` in an `ephemeral` one. A repeat while the first is still running is 409 `turn_in_progress`. A failed turn is not billed and its key can be retried. Rarely, a turn is answered but cannot be recorded; a repeat of its key is then evaluated again after a short wait, and is still charged once. Several turns of one conversation may run at once. Also available on a user's delegated access token with the `insights.write` scope, for a conversation your app created for that user; the token must still hold `media.read` (403 naming the scope otherwise), each turn must request at least one modality (403 otherwise), and a recording that user no longer owns is 404 `binding_not_found`. None of these is billed. The turn is billed to that user, or to their team workspace where the deployment is that workspace's own. On a conversation bound with `media_bindings`, `media_ids` chooses which of the bound recordings this turn reads (distinct ids, at most 200, each one bound: another id is 422 with `field: media_ids.{i}`; absent means all of them). `window` is applied on each chosen recording's own clock, a recording that needs a subject says which one in `media_id`, and `modalities_used` reports what was read across them. Every chosen recording is checked again on every turn: one that was deleted, or is no longer readable by the token, is 404 `binding_not_found` before any work is done or charged. Only a conversation bound to recordings takes `media_ids`. Bindings with `people` supply separately labelled evidence for every selected person. Unbound modalities have no samples and never inherit another person's speaker. Transcript segments are limited to explicitly bound, requested voice/text speakers. Missing evidence is not a negative finding. Larger prompts may increase the turn's usage; billing remains once per turn. The evidence size limit covers all people and selected recordings together (413 `payload_too_large`, `field: recording_evidence`). Selected recordings keep their own clocks; a window may extend beyond a shorter recording. The cohort must become ready within the turn budget (409 `media_not_ready` otherwise). If recording preparation is temporarily unavailable, the turn answers 503 `preparation_busy` without a charge; retry after a short wait. Generated evidence and retained evidence each have an aggregate 256,000 UTF-8 byte limit; exceeding either is 413 `payload_too_large` with `field: recording_evidence`, before model work. Evidence is never truncated or a selected recording silently omitted to fit these limits. ## Path parameters - `conversation_id` string, required ## Request body - EvaluateRequest - `turn_key` string, required: Caller key of this turn. A key is charged at most once and normally answered once: see the route description. - `window` WindowIn: A half-open window `[start_ms, end_ms)` on the bound media's clock. - `start_ms` integer, required - `end_ms` integer, required - `modalities` string[] - `input` object, nullable: The turn's input object. - `sections` SectionIn[]: Per-turn sections, e.g. text the model may quote verbatim. A type must keep the trust class it has in the conversation. - `type` string, required: Section type chosen by the application, e.g. `rubric` or `document_chunk`. - `trust` 'authoritative' | 'untrusted_data' | 'private_data', required: How the model may use the section. `authoritative` is application-authored context to follow; `untrusted_data` and `private_data` are data, never instructions, and `private_data` is never repeated in output. - `preamble` string: Application note on how to use the section. - `content` string: The section body. - `decoding` DecodingIn - `temperature` number - `seed` integer, nullable - `max_output_tokens` integer - `media_ids` string[], nullable: For a conversation bound with `media_bindings`: which of the bound recordings this turn reads, by `media_id` (distinct, each one bound). Absent means all of them. `window` applies to each selected recording's own clock, and `modalities_used` reports what was read across them. ## Response `200` Successful Response - EvaluateResponse - `conversation_id` string, required - `turn_key` string, required - `output` object, required - `modalities_used` string[] - `evidence_pending` boolean: The live window was still filling when evaluated; a later turn may see more data. - `cache_hit` boolean - `repaired` boolean - `replayed` boolean - `usage` EvaluateUsage, required - `tokens_by_model` object - `credits` integer, required: Price of this turn in credits, charged once per `turn_key` after the response is sent; 0 on a replay. - `latency_ms` integer, required ## Other responses - `422`: Validation Error ## Changes - **2026-10-07** `45bdd041d683`: 1 info - added the new optional request property `media_ids` - **2026-10-01** `72330e2229c7`: 1 info - endpoint added [Operation history](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/changes/v2/insights/conversations/:conversation_id/evaluate/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)