---
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.

---

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