---
title: "Get Evaluation Results"
method: GET
path: "/v3/evals/{eval_id}"
tags: ["file-search"]
---

# Get Evaluation Results

`GET /v3/evals/{eval_id}`

Status, progress, per-config scorecards, billing and per-case results for an eval. `scorecards` is `{}` and `billing` is `null` until the eval is terminal (`completed`, `completed_with_errors`, or `failed`). Items are paged by `items_limit` (default 100, max 500) and `items_cursor`; each item carries a result object per config name. Recall, MRR and nDCG are over scored units only; a failed query is counted in `failed`, never scored as a miss. Evals of a deleted collection return `404`. Metric definitions are on the [Evaluations](/guides/evaluations) guide.

## Path parameters

- `eval_id` string, required

## Query parameters

- `items_limit` integer
- `items_cursor` string, nullable

## Response `200`

The eval, with items paged.

- EvalResponseV3 — One shape for the 201 accept body, the 200 idempotent replay, and GET.
  - `billing` EvalBillingV3
    - `billable_units` integer, required
    - `failed_configs` string[]
    - `skipped_units` integer, required
  - `collection_name` string, required
  - `completed_at` string, nullable
  - `configs` ResolvedConfigV3[], required
    - `explicit_fields` string[], required
    - `name` string, required
    - `query` ResolvedQueryConfigV3, required — Every Query v3 field, defaults filled in, rerank always in object form.
      - `boost` ResolvedQueryConfigV3BoostItems[]
      - `exclude_chunk_types` string[]
      - `filter` ResolvedQueryConfigV3Filter
      - `include` object
      - `limit` integer, required
      - `max_chunks_per_document` integer, nullable
      - `relation_direction` string
      - `relation_types` string[], nullable
      - `rerank` ResolvedRerankV3, required
        - `candidate_limit` integer, nullable
        - `enabled` boolean, required
        - `model` string, nullable
      - `semantic_ratio` number, double, required
  - `created_at` string, required
  - `environment` string, nullable
  - `error_code` string, nullable
  - `error_message` string, nullable
  - `eval_id` string, required
  - `idempotency_key` string, required
  - `items` EvalItemV3[]
    - `error_code` string, nullable
    - `error_message` string, nullable
    - `expected_document_ids` string[], nullable
    - `expected_files` string[], required
    - `filters` EvalItemV3Filters
    - `id` string, required
    - `query` string, required
    - `results` object
    - `status` 'pending' | 'running' | 'scored' | 'error', required
  - `items_page` EvalItemsPageV3, required
    - `limit` integer, required
    - `next_cursor` string, nullable
    - `total` integer, required
  - `preview` EvalPreviewV3, required
    - `billable_units` integer, required
    - `cases` integer, required
    - `cases_error` integer, required
    - `configs` integer, required
    - `units` integer, required
  - `progress` EvalProgressV3, required
    - `cases_error` integer, required
    - `cases_total` integer, required
    - `configs_failed` integer, required
    - `configs_total` integer, required
    - `elapsed_seconds` integer, required
    - `eta_seconds` integer, nullable
    - `percent` integer, required
    - `qps` number, double, nullable
    - `units_completed` integer, required
    - `units_error` integer, required
    - `units_failed` integer, required
    - `units_total` integer, required
  - `request_id` string, required
  - `scorecards` object
  - `started_at` string, nullable
  - `status` 'pending' | 'running' | 'completed' | 'completed_with_errors' | 'failed', required
  - `updated_at` string, required
  - `upload_id` string, required

## Other responses

- `400` — `INVALID_ID_PREFIX` (ids start with `eval_`) or `INVALID_CURSOR`.
- `401` — Missing or invalid authentication.
- `403` — API key does not have the query permission for this collection.
- `404` — Collection not found (or an eval / upload that belongs to another organization: no existence oracle).

## Changes

- **2026-09-24** `61a9364ad042` — 4 breaking, 16 info
  - the response's body type changed from no type to `object` for status `400`
  - the response's body type changed from no type to `object` for status `401`
  - the response's body type changed from no type to `object` for status `403`
  - the response's body type changed from no type to `object` for status `404`
  - …16 more
- **2026-09-16** `e82391fa5b0b` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/runcaptain/apis/api-reference/changes/v3/evals/:eval_id/get.md)

---

[API](https://skmtc.dev/runcaptain/apis/api-reference.md) · [All operations](https://skmtc.dev/runcaptain/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc.dev/runcaptain/apis/api-reference/revisions/ac61e472bb7d?raw)