---
title: "Start evaluation run"
method: POST
path: "/api/v1/evaluations"
tags: ["evaluations"]
---

# Start evaluation run

`POST /api/v1/evaluations`

Kick off a GenAI evaluation run on MLflow traces. Returns a run_id that can be used to retrieve the full report via GET /evaluations/{run_id}.

## Request body

- EvaluationRequest — Request body for POST /api/v1/evaluations.
  - `trace_ids` string[], nullable — Optional list of specific trace IDs to evaluate (max 100).
  - `limit` integer, nullable — Optional maximum number of traces to evaluate (1-1000).
  - `from_last_days` integer — Number of days to look back for traces (0-365, default: 1).

## Response `200`

Successful Response

- EvaluationRunResponse — Response body for POST /api/v1/evaluations. The POST endpoint returns immediately with ``status="pending"``; the actual evaluation runs as a background ``asyncio.create_task`` so the event loop stays free to serve other requests (VAL-SEC-009, VAL-SEC-011). Clients poll ``GET /api/v1/evaluations/{run_id}`` to observe the ``pending`` -> ``running`` -> ``completed`` transition (VAL-SEC-010).
  - `run_id` string, required — Unique identifier for this evaluation run.
  - `status` string — Lifecycle status of the run: ``pending`` (queued/just-started), ``running`` (background task executing), ``completed`` (report available), or ``failed`` (evaluation error).

## Other responses

- `401` — Authentication is required or the provided token is invalid.
- `422` — Validation Error
- `503` — MLflow or evaluation services are unavailable.

## Changes

- **2026-06-27** `a869a5b71715` — 1 info
  - added the optional property `status` to the response with the `200` status
- **2026-06-27** `82f26b74d059` — 4 warning, 1 info
  - the `from_last_days` request property's max was set to `365.00`
  - the `limit/anyOf[subschema #1]/` request property's max was set to `1000.00`
  - the `from_last_days` request property's min was set to `0.00`
  - the `limit/anyOf[subschema #1]/` request property's min was set to `1.00`
  - …1 more
- **2026-06-26** `5418ba3bbaef` — 1 info
  - endpoint added
- **2026-03-19** `78507b29ed8f` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/qredence/apis/fleet-rlm/changes/api/v1/evaluations/post.md)

---

[API](https://skmtc.dev/qredence/apis/fleet-rlm.md) · [All operations](https://skmtc.dev/qredence/apis/fleet-rlm/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/qredence/fleet-rlm/revisions/0be3db8d7e28/schema)