---
title: "Run evaluation"
method: POST
path: "/v1/retrievers/{retriever_id}/evaluations"
tags: ["Retriever Evaluations"]
---

# Run evaluation

`POST /v1/retrievers/{retriever_id}/evaluations`

Evaluate a retriever's quality using a ground truth dataset. Returns immediately with a task ID - evaluation runs asynchronously.

## Path parameters

- `retriever_id` string, required

## Request body

- StartEvaluationRequest — Request to start an evaluation.
  - `dataset_name` string, required — Name of the evaluation dataset to use
  - `evaluation_config` EvaluationConfig — Configuration for an evaluation run.
    - `k_values` integer[], nullable — K values for Precision@K, Recall@K, NDCG@K, etc.
    - `metrics` string[], nullable — List of metrics to calculate. Available: precision, recall, f1, f2, map, ndcg, mrr. f2 is the recall-weighted F-beta (beta=2) — useful when missing a relevant doc costs more than a false positive.

## Response `202`

Successful Response

- StartEvaluationResponse — Response when starting an evaluation.
  - `task_id` string, required — Task ID for tracking progress
  - `evaluation_id` string, required — Evaluation ID
  - `task_type` string — Task type
  - `status` string — Initial status
  - `created_at` string, required — Creation timestamp

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/220a3b263fda/schema)