---
title: "Create and launch evaluation runs"
method: POST
path: "/api/eval-runs/"
tags: ["eval-runs"]
---

# Create and launch evaluation runs

`POST /api/eval-runs/`

## Request

- Base URL: `https://api.overmindlab.ai`
- URL: `https://api.overmindlab.ai/api/eval-runs/`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`
  - API key in cookie `sessionid`
  - API key in header `X-Api-Key`
  - HTTP bearer

One run per target, all sharing a `group`. The baseline target is compared with every other target once both complete.

## Request body

- EvalRunCreateRequest
  - `project` string, uuid, required
  - `dataset` string, uuid, required
  - `cell` string, uuid, nullable
  - `eval_set` string, uuid, nullable
  - `judge_model` union: Explanation judge for this run. Blank uses the configured default. * `` - * `gpt-5.6-luna` - gpt-5.6-luna * `gpt-5.6-terra` - gpt-5.6-terra * `claude-sonnet-5` - claude-sonnet-5 * `claude-haiku-4-5` - claude-haiku-4-5 * `gemini-3.1-pro-preview` - gemini-3.1-pro-preview * `gemini-3.8-flash` - gemini-3.8-flash * `deepseek-v3.2` - deepseek-v3.2
    - 'gpt-5.6-luna' | 'gpt-5.6-terra' | 'claude-sonnet-5' | 'claude-haiku-4-5' | 'gemini-3.1-pro-preview' | 'gemini-3.8-flash' | 'deepseek-v3.2': * `` - * `gpt-5.6-luna` - gpt-5.6-luna * `gpt-5.6-terra` - gpt-5.6-terra * `claude-sonnet-5` - claude-sonnet-5 * `claude-haiku-4-5` - claude-haiku-4-5 * `gemini-3.1-pro-preview` - gemini-3.1-pro-preview * `gemini-3.8-flash` - gemini-3.8-flash * `deepseek-v3.2` - deepseek-v3.2
    - ''
  - `targets` EvalRunTargetRequest[], required
    - `label` string
    - `mode` 'recorded' | 'generate': * `recorded` - recorded * `generate` - generate
    - `model_name` string
    - `model_ref` string, uuid, nullable
    - `params` object
    - `is_baseline` boolean
    - `output_tokens` integer
  - `name` string, required
  - `description` string
  - `max_items` integer
  - `sampling` number, double

## Response `201`

- EvalRunGroup
  - `group` string, uuid, required
  - `runs` EvalRun[], required
    - `id` string, uuid, required
    - `project` string, uuid, required
    - `name` string, required
    - `description` string, required
    - `label` string, required
    - `dataset` string, uuid, nullable, required
    - `dataset_name` string, required
    - `capability_id` string, uuid, required
    - `capability_name` string, required
    - `cell` string, uuid, nullable, required
    - `cell_info` object, nullable, required
    - `max_items` integer, required
    - `sampling` number, double, required
    - `eval_set` string, uuid, nullable, required
    - `matrix` unknown, required
    - `mode` 'recorded' | 'generate' | 'provided', required: * `recorded` - Recorded * `generate` - Generate * `provided` - Provided
    - `model_ref` string, uuid, nullable, required
    - `model_name` string, required
    - `resolved_model` string, required
    - `params` unknown, required
    - `group` string, uuid, required
    - `is_baseline` boolean, required
    - `judge_model` string, required
    - `status` 'pending' | 'running' | 'completed' | 'failed' | 'cancelled', required: * `pending` - Pending * `running` - Running * `completed` - Completed * `failed` - Failed * `cancelled` - Cancelled
    - `error` string, required
    - `summary` unknown, required
    - `progress` EvalRunProgress, required
      - `rows` integer, required
      - `waiting` integer, required
      - `running` integer, required
      - `done` integer, required
      - `errored` integer, required
      - `phase` 'preparing' | 'generating' | 'scoring', required: * `preparing` - preparing * `generating` - generating * `scoring` - scoring
    - `origin` string, required
    - `optimizer_experiment` string, uuid, nullable, required
    - `triggered_by` integer, nullable, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `completed_at` string, date-time, nullable, required

---

[API](https://skmtc.dev/overmindlab/apis/overmind-api.md) - [All operations](https://skmtc.dev/overmindlab/apis/overmind-api/llms.txt) - [OpenAPI document](https://skmtc.dev/overmindlab/apis/overmind-api/revisions/0ecfd39e80c6?raw)