---
title: "Score predictions vs ground truth (stateless)"
method: POST
path: "/v1/evaluations/score"
tags: ["Retriever Evaluations"]
---

# Score predictions vs ground truth (stateless)

`POST /v1/evaluations/score`

Compute quality metrics (Precision@K, Recall@K, F1@K, F2@K) for precomputed predictions vs ground truth, with NO retriever, namespace, or persistence. Each item's `predicted` and `ground_truth` are treated as SETS. Send a single pair (`predicted` + `ground_truth`) or an `items` batch. Returns per-item scores and the macro-average across items. Auth only (no X-Namespace). This is the stateless counterpart to the retriever-scoped evaluation runs — use it to dogfood F1/F2 on extraction/generation benchmarks.

## Request body

- ScorePredictionsRequest — Score precomputed predictions vs ground truth, statelessly. Send EITHER a single pair (``predicted`` + ``ground_truth``) or an ``items`` batch (score many predictions in one call — the shape a benchmark of N predictions wants). Exactly one form is required.
  - `predicted` string[], nullable — Single-pair form: predicted terms/ids. Pair with ground_truth.
  - `ground_truth` string[], nullable — Single-pair form: ground-truth terms/ids. Pair with predicted.
  - `items` ScoreItem[], nullable — Batch form: a list of {predicted, ground_truth} pairs.
    - `predicted` string[] — Predicted terms or ids (treated as a set).
    - `ground_truth` string[] — Ground-truth terms or ids (treated as a set).
  - `metrics` string[] — Metrics to compute. Allowed: precision, recall, f1, f2.
  - `k` integer, nullable — Cutoff: score only the first k predicted items. Default: all.

## Response `200`

Successful Response

- ScorePredictionsResponse — Per-item and aggregate (macro-mean) scores.
  - `metrics` string[], required — Metrics computed, in request order.
  - `k` integer, nullable — Cutoff applied, if any.
  - `count` integer, required — Number of items scored.
  - `per_item` object[], required — Each item's {metric: value} in [0.0, 1.0].
  - `aggregate` object, required — Macro-average (mean over items) of each metric.

## 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/6e8256aacbc5/schema)