---
title: "Public Create Eval Run"
method: POST
path: "/v1/evals/{slug}/runs"
tags: ["public-api"]
---

# Public Create Eval Run

`POST /v1/evals/{slug}/runs`

Record a terminal eval run (with optional per-case results) for a task.

## Path parameters

- `slug` string, required

## Headers

- `authorization` string, nullable

## Request body

- EvalRunIngestInput — A terminal run pushed by an external pipeline. `overall_score` is the required headline score, in whatever unit the group measures — a rate sits in [0, 1], an SNR does not. There is no upper bound; the viewer derives its scales from the group's own data. `cases` is optional — a run may be summary-only.
  - `model` string, required — Model name snapshot, e.g. wilson-v3-step200
  - `dataset_train` string — Training dataset snapshot
  - `dataset_eval` string — Eval dataset snapshot, e.g. apex-curated-eval-subset@2026-07-10
  - `variant` string — Mutation/question variant within the task, e.g. v2-polar-positive
  - `reference_label` string — Mark this run as a reference instead of a scored datapoint, e.g. "random", "SOTA", "gpt-5 baseline". Reference runs are excluded from every score rollup and the group chart draws them as dotted horizontal lines captioned with this label. Empty (default) = an ordinary scored run.
  - `input_template` string — The {vars} question template that defines the variant
  - `grading` string — How the run was graded / answer logic
  - `metric` string — Name of the headline metric overall_score normalizes
  - `output_location` string — Where the pipeline stored the raw outputs
  - `overall_score` number, required
  - `status` 'completed' | 'failed', required
  - `metrics` object
  - `started_at` string, date-time, nullable
  - `finished_at` string, date-time, nullable
  - `created_at` string, date-time, nullable — Optional original record time, preserved by export→replay syncs. The timeline falls back to it when finished_at is unset; omitted = now.
  - `source` string — Which pipeline pushed this run
  - `error` string
  - `cases` EvalRunCaseIngest[]
    - `input_preview` string
    - `response_text` string
    - `score` number, nullable
    - `scores` object
    - `trace_id` string, nullable

## Response `201`

Successful Response

- EvalRunSummary — One run row in the task page's runs table.
  - `id` string, uuid, required
  - `model_slug` string, required
  - `dataset_train` string, required
  - `dataset_eval` string, required
  - `variant` string, required
  - `reference_label` string, required — Non-empty for reference runs, which are excluded from the score rollups
  - `overall_score` number, required
  - `status` 'completed' | 'failed', required
  - `error` string, required
  - `source` string, required
  - `created_at` string, required
  - `started_at` string, nullable, required
  - `finished_at` string, nullable, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/trainloop/apis/trainloop-api.md) · [All operations](https://skmtc.dev/trainloop/apis/trainloop-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/trainloop/trainloop-api/revisions/aedb0e4b59f8/schema)