---
title: "Create Eval Run"
method: POST
path: "/api/v1/console/evals/runs"
tags: ["evals"]
---

# Create Eval Run

`POST /api/v1/console/evals/runs`

## Request

- Base URL: `https://ndi-api.nace.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://ndi-api.nace.ai/api/v1/console/evals/runs`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/nace/apis/ndi-service/docs/api/v1/console/evals/runs/post.ts> (a function with typed inputs; its response is checked against the schema)

Start a run over the selected samples. Poll the run for progress.

## Headers

- `x-api-key` string, nullable

## Request body

- CreateEvalRunRequest
  - `name` string, nullable
  - `params` EvalRunParams: What to run and how. An empty selection means every runnable sample.
    - `sample_ids` string[]
    - `layer` string, nullable
    - `tags` string[]
    - `k_override` integer, nullable: Overrides each sample's own `k_runs`.
    - `judge_model` string, nullable
    - `use_judge` boolean
    - `timeout_seconds` number, nullable: Overrides every selected sample's rollout timeout.
    - `max_concurrent_samples` integer

## Response `202`

Successful Response

- EvalRun
  - `eval_run_id` string, uuid, required
  - `status` string, required: `queued` | `running` | `succeeded` | `failed`. Open enum — never switch exhaustively.
  - `name` string, nullable
  - `created_by_email` string, nullable: Who started it. Null once that account is gone; the run's numbers stay.
  - `params` EvalRunParams, required: What to run and how. An empty selection means every runnable sample.
    - `sample_ids` string[]
    - `layer` string, nullable
    - `tags` string[]
    - `k_override` integer, nullable: Overrides each sample's own `k_runs`.
    - `judge_model` string, nullable
    - `use_judge` boolean
    - `timeout_seconds` number, nullable: Overrides every selected sample's rollout timeout.
    - `max_concurrent_samples` integer
  - `workflow_id` string, nullable
  - `samples_total` integer, required
  - `samples_passed` integer, required
  - `samples_failed` integer, required
  - `error` string, nullable: Set when the run itself broke, not when a sample failed its metrics.
  - `created_at` string, date-time, required
  - `started_at` string, date-time, nullable
  - `finished_at` string, date-time, nullable

## Other responses

- `400`: Bad Request
- `401`: Missing or invalid bearer token.
- `402`: Payment Required
- `403`: An API key was sent, the account is not Nace staff, or it is disabled.
- `404`: No console account for this identity — sign in first.
- `409`: Conflict
- `413`: Request Entity Too Large
- `422`: Unprocessable Entity
- `500`: Internal Server Error
- `503`: The eval harness or its worker queue is not available on this deployment.

---

[API](https://skmtc.dev/nace/apis/ndi-service.md) - [All operations](https://skmtc.dev/nace/apis/ndi-service/llms.txt) - [OpenAPI document](https://skmtc.dev/nace/apis/ndi-service/revisions/d9d1f8ec2207?raw)