Evaluate
Single-shot evaluation endpoint. Submit a complete conversation and receive a reward score. With grading, grade only the final assistant reply against the frozen configuration.
Store turn readings
For a whole-conversation evaluation, addstore to save the score, per-fact readings, and individual judge readings:
capture_session_id must identify a recording owned by your organization and linked to the scenario being evaluated. turn_index is the operator turn number this evaluation scores up to.
repeats is an optional positive integer for this request. Omit it to use the reviewed Qwen3-32B default of 5. Judges without reviewed defaults require an explicit count. An override stays in its stored recipe and never changes the default. Calibrated detectors keep their own repeat counts. Detectors that return a list of items, such as the terminology scan, use one read.
The response includes run_id at every score access tier. The full tier also includes observations, with each fact’s status, values, tested turns, and evidence. The scores and reward-only tiers withhold those observations. The stored score uses the scenario’s scoring tree; a returned reward with weight overrides can differ.
The submitted messages must match the recording prefix at turn_index, including each role and its text. Stored evaluations accept a single client boundary for that turn and reject tool calls.
Omit store to evaluate without saving a run. store is accepted only for whole-conversation evaluation, and cannot be combined with grading.
Final-operator-reply grading
Sendgrading: { "type": "final-operator-reply", "scope": "response-metrics" } to grade only the last assistant message. Earlier messages are context the judge reads but never credits, and only the scenario’s linked success and failure criteria are judged. The messages must alternate between user (the persona) and assistant (the model under grading), with at least three context messages before the graded reply; system messages and tool calls are rejected in this mode.
The response carries the frozen grading configuration and a judgment receipt: one criterion_results row per criterion with its value, its status, the turn it was tested at and an exact quote from the graded reply, plus the judge configuration that produced it.
Freeze the configuration first with Evaluate configuration and send its grading_config_sha256 back as expected_grading_config_sha256. When the configuration compiled for the request differs, the response is 409 and no judge runs.
scoring_version, grading_config_sha256, history_sha256, response_sha256, target_message_id, target_index, request_id and trace_id, and omits criterion_results, criterion_sources, criterion_ids, completed_criterion_ids, judge_execution, judge_configuration and detector_provenance. The scores and full tiers receive the full receipt.Authorizations
API key obtained from Labs Portal
Headers
Judge model ID. Must match judge_model when both are supplied.
bedrock-llama-3.1-70b, bedrock-llama-3.1-8b, bedrock-llama-3-70b, bedrock-llama-3-8b, minimax-m2.5, mistral-7b, mistral-large-2402, mistral-small-2402, mixtral-8x7b, kimi-k3, nemotron-super-120b, bedrock-gpt-5.4, bedrock-gpt-5.5, bedrock-gpt-5.6-luna, bedrock-gpt-5.6-sol, bedrock-gpt-5.6-terra, bedrock-gpt-6-astra, bedrock-gpt-6-luna, bedrock-gpt-6-sol, bedrock-gpt-6.1-sol, palmyra-vision-7b, bedrock-grok-4.6, bedrock-grok-4.7, glm-5, glm-5.3, claude-haiku-5-5, claude-sonnet-5, claude-sonnet-5-5, claude-opus-4-7, claude-opus-4-8, claude-opus-5, claude-opus-5-5, claude-fable-5, claude-fable-5-1, claude-4-5-haiku, claude-sonnet-4-6, claude-opus-4-5, claude-opus-4-6, glm-4.7-flash, glm-4.7, nova-micro, nova-lite, nova-pro, nova-2-lite, deepseek-r1, deepseek-v3, deepseek-v3.2, kimi-k2-thinking, kimi-k2.5, minimax-m2, minimax-m2.1, bedrock-qwen3-32b, bedrock-qwen3-235b, bedrock-qwen3-coder-30b, bedrock-qwen3-coder-480b, bedrock-qwen3-coder-next, bedrock-qwen3-next-80b, bedrock-qwen3-vl-235b, mistral-large-3, devstral-123b, magistral-small, pixtral-large, ministral-14b, ministral-8b, ministral-3b, bedrock-llama-4-maverick, bedrock-llama-4-scout, bedrock-llama-3.3-70b, gemma-3-27b, gemma-3-12b, gemma-3-4b, nemotron-nano-30b, nemotron-nano-12b, nemotron-nano-9b, bedrock-gpt-oss-120b, bedrock-gpt-oss-20b, palmyra-x5, palmyra-x4 Body
The collection slug containing the scenario
The scenario slug to evaluate against
The conversation history to evaluate. With grading: alternating user and assistant messages, the last one the assistant reply under grading.
bedrock-llama-3.1-70b, bedrock-llama-3.1-8b, bedrock-llama-3-70b, bedrock-llama-3-8b, minimax-m2.5, mistral-7b, mistral-large-2402, mistral-small-2402, mixtral-8x7b, kimi-k3, nemotron-super-120b, bedrock-gpt-5.4, bedrock-gpt-5.5, bedrock-gpt-5.6-luna, bedrock-gpt-5.6-sol, bedrock-gpt-5.6-terra, bedrock-gpt-6-astra, bedrock-gpt-6-luna, bedrock-gpt-6-sol, bedrock-gpt-6.1-sol, palmyra-vision-7b, bedrock-grok-4.6, bedrock-grok-4.7, glm-5, glm-5.3, claude-haiku-5-5, claude-sonnet-5, claude-sonnet-5-5, claude-opus-4-7, claude-opus-4-8, claude-opus-5, claude-opus-5-5, claude-fable-5, claude-fable-5-1, claude-4-5-haiku, claude-sonnet-4-6, claude-opus-4-5, claude-opus-4-6, glm-4.7-flash, glm-4.7, nova-micro, nova-lite, nova-pro, nova-2-lite, deepseek-r1, deepseek-v3, deepseek-v3.2, kimi-k2-thinking, kimi-k2.5, minimax-m2, minimax-m2.1, bedrock-qwen3-32b, bedrock-qwen3-235b, bedrock-qwen3-coder-30b, bedrock-qwen3-coder-480b, bedrock-qwen3-coder-next, bedrock-qwen3-next-80b, bedrock-qwen3-vl-235b, mistral-large-3, devstral-123b, magistral-small, pixtral-large, ministral-14b, ministral-8b, ministral-3b, bedrock-llama-4-maverick, bedrock-llama-4-scout, bedrock-llama-3.3-70b, gemma-3-27b, gemma-3-12b, gemma-3-4b, nemotron-nano-30b, nemotron-nano-12b, nemotron-nano-9b, bedrock-gpt-oss-120b, bedrock-gpt-oss-20b, palmyra-x5, palmyra-x4 Store fact readings for a whole-conversation evaluation.
Reward configuration. Controls which scorers run and their weights. Omitted quality weight keys default to 0, so only specified scorers execute. Does not apply with grading.
Reply-only grading. Omit to score the whole conversation with the scenario's scorers. The response carries the frozen configuration and a judgment receipt; at the reward-only score access tier it omits criterion_results, criterion_sources, criterion_ids, completed_criterion_ids, judge_execution, judge_configuration and detector_provenance.
The grading_config_sha256 frozen by POST /api/v1/evaluate/configuration. When it differs from the configuration compiled for this request, the response is 409 and no judge runs. Requires grading.
^[a-f0-9]{64}$Response
Success
Reward score (0 to 1)
0 <= x <= 1Version of the scoring algorithm used: 2.0.0 for whole-conversation scoring, next-turn-fql-v1 for final-operator-reply grading
Stored scoring run. Present when store was requested.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Per-fact readings from the stored run. Included only with full score access.
bedrock-llama-3.1-70b, bedrock-llama-3.1-8b, bedrock-llama-3-70b, bedrock-llama-3-8b, minimax-m2.5, mistral-7b, mistral-large-2402, mistral-small-2402, mixtral-8x7b, kimi-k3, nemotron-super-120b, bedrock-gpt-5.4, bedrock-gpt-5.5, bedrock-gpt-5.6-luna, bedrock-gpt-5.6-sol, bedrock-gpt-5.6-terra, bedrock-gpt-6-astra, bedrock-gpt-6-luna, bedrock-gpt-6-sol, bedrock-gpt-6.1-sol, palmyra-vision-7b, bedrock-grok-4.6, bedrock-grok-4.7, glm-5, glm-5.3, claude-haiku-5-5, claude-sonnet-5, claude-sonnet-5-5, claude-opus-4-7, claude-opus-4-8, claude-opus-5, claude-opus-5-5, claude-fable-5, claude-fable-5-1, claude-4-5-haiku, claude-sonnet-4-6, claude-opus-4-5, claude-opus-4-6, glm-4.7-flash, glm-4.7, nova-micro, nova-lite, nova-pro, nova-2-lite, deepseek-r1, deepseek-v3, deepseek-v3.2, kimi-k2-thinking, kimi-k2.5, minimax-m2, minimax-m2.1, bedrock-qwen3-32b, bedrock-qwen3-235b, bedrock-qwen3-coder-30b, bedrock-qwen3-coder-480b, bedrock-qwen3-coder-next, bedrock-qwen3-next-80b, bedrock-qwen3-vl-235b, mistral-large-3, devstral-123b, magistral-small, pixtral-large, ministral-14b, ministral-8b, ministral-3b, bedrock-llama-4-maverick, bedrock-llama-4-scout, bedrock-llama-3.3-70b, gemma-3-27b, gemma-3-12b, gemma-3-4b, nemotron-nano-30b, nemotron-nano-12b, nemotron-nano-9b, bedrock-gpt-oss-120b, bedrock-gpt-oss-20b, palmyra-x5, palmyra-x4 Optional breakdown of individual score dimensions. When omitted, only the combined reward is provided.
Textual reasoning per score dimension. Only included for subscriptions with full score access.
This request, also sent as the X-Request-ID header.
The judge model and its frozen routing and sampling settings.
"response-metrics"Which scenario success or failure metric each graded criterion was compiled from.
1Which scoring tree graded the reply: the dimension-compiled tree of a preset scenario, or the hand-authored custom tree.
compiler, custom-author Hash of the compiled criteria, the judge, the target position and the protocol version. Send it back as expected_grading_config_sha256 to refuse grading on drift.
^[a-f0-9]{64}$^[a-f0-9]{64}$The identifier the graded reply is given, derived from the history.
1The position of the graded reply, one past the last context message.
0 <= x <= 9007199254740991"operator"1pinned-target-protocol when any criterion is read by its own pinned detector, calibrated under this reply-only protocol.
uncalibrated-target-protocol, pinned-target-protocol - Option 1
- Option 2
1^[a-f0-9]{64}$11Additional evaluation metadata