Skip to main content
POST
Score predictions vs ground truth (stateless)

Authorizations

Authorization
string
header
required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing header returns 403; an invalid or revoked key returns 401.

Body

application/json

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[] | null

Single-pair form: predicted terms/ids. Pair with ground_truth.

ground_truth
string[] | null

Single-pair form: ground-truth terms/ids. Pair with predicted.

items
ScoreItem · object[] | null

Batch form: a list of {predicted, ground_truth} pairs.

metrics
string[]

Metrics to compute. Allowed: precision, recall, f1, f2.

k
integer | null

Cutoff: score only the first k predicted items. Default: all.

Required range: x >= 1

Response

Successful Response

Per-item and aggregate (macro-mean) scores.

metrics
string[]
required

Metrics computed, in request order.

count
integer
required

Number of items scored.

per_item
Per Item · object[]
required

Each item's {metric: value} in [0.0, 1.0].

aggregate
Aggregate · object
required

Macro-average (mean over items) of each metric.

k
integer | null

Cutoff applied, if any.