---
title: "Read an evaluation run's summary"
method: GET
path: "/api/v1/public/evaluation-runs/{run_id}"
tags: ["Offline Eval"]
---

# Read an evaluation run's summary

`GET /api/v1/public/evaluation-runs/{run_id}`

## Request

- Base URL: `https://app.traceroot.ai`
- URL: `https://app.traceroot.ai/api/v1/public/evaluation-runs/{run_id}`
- Auth: HTTP bearer

Read a run's own summary: status, result counts, and per-score and per-metric
means over the run's results.

Typed rather than left to the catch-all so it appears in the published OpenAPI: an
endpoint a CLI is expected to call must be in the contract the CLI generates from.
Summary only, so the response is bounded by scorer count rather than case count.

Comparing two runs is not part of this read. It is a different question with its own
trust rules, and an optional parameter here would be too easily confused with the
baseline a run stores at registration.

## Path parameters

- `run_id` string, required

## Query parameters

- `project_id` string, nullable: Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.

## Response `200`

Successful Response

- ReadRunResponse: A run's SUMMARY — deliberately no per-case rows, so the payload is bounded by scorer count rather than case count and needs no truncation flag.
  - `candidate_version` string, required
  - `completed_at` string, nullable
  - `dataset_id` string, required
  - `dataset_version_id` string, required
  - `environment` string, required
  - `errored_count` integer, required
  - `evaluation_id` string, required
  - `evaluation_key` string, nullable
  - `evaluation_name` string, required
  - `evaluation_run_id` string, required
  - `failed_count` integer, required
  - `metrics` RunMetricItem[]
    - `direction` 'higher_is_better' | 'lower_is_better' | 'none', required
    - `name` string, required
    - `observed_count` integer, required: How many results reported a usable value for this score or metric.
    - `unit` '$' | 'tok' | 'ms' | 'count', nullable
    - `value` number, nullable: The run's own mean over observed_count results. Null when nothing was observed, and always for a categorical score or one that stored labels and numbers together.
    - `value_type` 'numeric' | 'boolean' | 'categorical', required: The scorer's declared kind, else the kind it stored. Every derived metric is numeric.
  - `not_scored_count` integer, required
  - `passed_count` integer, required
  - `result_count` integer, required
  - `run_number` integer, required
  - `run_path` string, required
  - `run_url` string, required
  - `scored_count` integer, nullable, required
  - `scorer_error_count` integer, nullable, required
  - `scores` RunMetricItem[]
    - `direction` 'higher_is_better' | 'lower_is_better' | 'none', required
    - `name` string, required
    - `observed_count` integer, required: How many results reported a usable value for this score or metric.
    - `unit` '$' | 'tok' | 'ms' | 'count', nullable
    - `value` number, nullable: The run's own mean over observed_count results. Null when nothing was observed, and always for a categorical score or one that stored labels and numbers together.
    - `value_type` 'numeric' | 'boolean' | 'categorical', required: The scorer's declared kind, else the kind it stored. Every derived metric is numeric.
  - `started_at` string, required
  - `status` 'running' | 'completed' | 'completed_with_errors' | 'failed' | 'incomplete' | 'cancelled', required
  - `task_error_count` integer, nullable, required

## Other responses

- `400`: Invalid request
- `401`: Authentication failed
- `403`: No access to this project, or the run is outside the plan's retention window
- `404`: Not found
- `422`: Validation error
- `429`: Rate limit exceeded
- `503`: Authentication service unavailable

---

[API](https://skmtc.dev/traceroot/apis/traceroot-public-api.md) - [All operations](https://skmtc.dev/traceroot/apis/traceroot-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/traceroot/apis/traceroot-public-api/revisions/ce6aef96c0d6?raw)