---
title: "Compare Evaluations"
method: POST
path: "/compare_evaluations"
---

# Compare Evaluations

`POST /compare_evaluations`

Compare two session evaluations and return a detailed comparison report.

This endpoint evaluates both sessions (using cache if available) and generates
a comprehensive comparison across 5 dimensions with AI-generated justifications.

## Request body

- CompareEvaluationsRequestBody — Request body for comparing two session evaluations.
  - `session_a_id` string, required — First session ID to compare
  - `session_b_id` string, required — Second session ID to compare
  - `evaluation_type` string, nullable — Evaluation type to use. If not provided, auto-detects from existing evaluations.
  - `skip_cache` boolean — Whether to skip cached evaluations
  - `num_runs` integer — Number of judgment runs per dimension for stability (1-50, recommend 3-5)

## Response `200`

Successful Response

- CompareEvaluationsResponse — Response containing the comparison report.
  - `comparison` SessionComparisonReport, required — Complete comparison report between two sessions.
    - `comparison_id` string
    - `incident_id` string, required
    - `incident_key` string, required
    - `session_a_id` string, required
    - `session_b_id` string, required
    - `evaluation_a_id` string, required — Evaluation ID for session A
    - `evaluation_b_id` string, required — Evaluation ID for session B
    - `dimensions` DimensionComparison[], required
      - `dimension` 'root_cause_accuracy' | 'evidence_recall' | 'investigation_efficiency', required — The three dimensions used to compare sessions.
      - `winner` 'session_a' | 'session_b' | 'tie', required
      - `justification` string, required — AI-generated explanation with specific examples and metrics
      - `confidence` number — Average judge confidence across all runs
      - `agreement_rate` number — Fraction of runs that agreed on the winner (1.0 = unanimous)
      - `num_runs` integer — Number of judgment runs performed for this dimension
      - `dimension_name` string, required
      - `is_stable` boolean, required — Whether the judgment is considered stable (high agreement + confidence).
    - `overall_winner` 'session_a' | 'session_b' | 'tie', required
    - `wins_by_session` object, required — Count of dimension wins per session
    - `summary` string, required — AI-generated overall comparison summary
    - `session_a_wins` integer, required
    - `session_b_wins` integer, required
    - `ties` integer, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/traversal/apis/fastapi.md) · [All operations](https://skmtc.net/traversal/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/traversal/fastapi/revisions/2134ebffd1ef/schema)