---
title: "Score Function Against (input, expected) Pairs"
method: POST
path: "/v3/eval/score"
tags: ["Function Accuracy"]
---

# Score Function Against (input, expected) Pairs

`POST /v3/eval/score`

**Score a function against a list of (input, expected) pairs.**

Submits a batch of `(input, expected)` pairs, runs the named function
over each input, and returns per-pair + aggregate accuracy metrics
comparing the function's actual output to the provided expected JSON.

Scoring runs asynchronously. The response carries a `scoreRunID`;
poll `GET /v3/eval/score/{scoreRunID}` until `status` is one of
`completed`, `error`, or `cancelled`.

`matchConfig` controls comparator behavior:
- `numericTolerance`: relative tolerance for numeric fields (0 = exact)
- `stringMatch`: `exact` (default) or `fuzzy` (Levenshtein ratio)
- `arrayMatch`: `by-index` (default; only mode in P0)
- `ignorePaths`: JSON Pointer paths to skip, supports `*` wildcards

## Request body

- EvalScoreRequestV3 — Request body for `POST /v3/eval/score`. Scores inputs against the named function. The inputs come from exactly one of two sources — provide either `pairs` (inline) or `datasetID` (a saved Golden Data Set), not both.
  - `functionName` string, required — Name of the function to score. Must be of type extract, transform, or analyze.
  - `functionVersionNum` integer — Optional version number to score against. P0: only the function's current version is accepted; passing a different version returns 422.
  - `pairs` EvalScorePairV3[] — Inline `(input, expected)` pairs to score, up to 1000 per request. Mutually exclusive with `datasetID`; provide exactly one.
    - `input` FileInput, required — A single file input with base64-encoded content. When using the Bem CLI, use `@path/to/file` in the `inputContent` field to automatically read and base64-encode the file: `--input.single-file '{"inputContent": "@file.pdf", "inputType": "pdf"}' --wait`
      - `inputType` 'csv' | 'docx' | 'email' | 'heic' | 'html' | 'jfif' | 'jpeg' | 'json' | 'heif' | 'm4a' | 'mov' | 'mp3' | 'mp4' | 'pdf' | 'png' | 'pptx' | 'text' | 'wav' | 'webp' | 'xls' | 'xlsx' | 'xml', required — The input type of the content you're sending for transformation. `jfif` is accepted as an alias for `jpeg` — JFIF is the same format under a different extension — and is normalized to `jpeg`, so responses and webhooks report `jpeg` for a JFIF upload. The undeclared alias `jpg` behaves the same way.
      - `inputContent` string, byte, required — Base64-encoded file content. In the Bem CLI, use `@path/to/file` to embed file contents automatically.
    - `expected` unknown, required
  - `datasetID` string — A saved Golden Data Set (`gds_…`) to score against. Mutually exclusive with `pairs`; provide exactly one. Its input / corrected / schema columns are resolved by column role. When it carries a `schema`-role column, scoring types each row against that ground-truth schema instead of the function's own schema — so results hold up as functions/schemas evolve.
  - `matchConfig` EvalMatchConfigV3 — Comparator configuration. All fields optional; conservative defaults.
    - `numericTolerance` number, double — Relative tolerance for numeric fields. `0` (default) means exact equality; `0.01` means ±1%.
    - `stringMatch` 'exact' | 'fuzzy' — `exact` (default) or `fuzzy`.
    - `fuzzyThreshold` number, double — Levenshtein-ratio threshold used when `stringMatch == "fuzzy"`. Range `[0, 1]`. Default `0.85`.
    - `arrayMatch` 'by-index' — P0 supports only `by-index`.
    - `ignorePaths` string[] — JSON Pointer paths to skip during comparison. The asterisk character matches arbitrary object keys / array indices. Example values: /metadata, /lineItems with asterisk segment, etc.

## Response `202`

The request has been accepted for processing, but processing has not yet completed.

- EvalScoreCreateResponseV3 — Returned by `POST /v3/eval/score`.
  - `scoreRunID` string, required — Run identifier. Use with `GET /v3/eval/score/{scoreRunID}`.
  - `status` 'pending' | 'initializing' | 'running' | 'completed' | 'error' | 'cancelled', required — Status values for an eval-score run.

## Other responses

- `400` — The server could not understand the request due to invalid syntax.

## Changes

- **2026-08-04** `643398900e5d` — 2 info
  - added the new optional request property `datasetID`
  - the request property `pairs` became optional
- **2026-08-03** `b0a6debb3458` — 1 info
  - added the new `jfif` enum value to the request property `pairs/items/input/allOf[#/components/schemas/FileInput]/inputType/allOf[#/components/schemas/InputType]/`
- **2026-07-13** `af0563bc9ef8` — 1 info
  - added the new `pptx` enum value to the request property `pairs/items/input/allOf[#/components/schemas/FileInput]/inputType/allOf[#/components/schemas/InputType]/`
- **2026-07-09** `9bc19fa12772` — 2 info
  - added the new `mov` enum value to the request property `pairs/items/input/allOf[#/components/schemas/FileInput]/inputType/allOf[#/components/schemas/InputType]/`
  - added the new `mp4` enum value to the request property `pairs/items/input/allOf[#/components/schemas/FileInput]/inputType/allOf[#/components/schemas/InputType]/`
- **2026-06-08** `fa35357c8574` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/bem-team/apis/bem-api/changes/v3/eval/score/post.md)

---

[API](https://skmtc.dev/bem-team/apis/bem-api.md) · [All operations](https://skmtc.dev/bem-team/apis/bem-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bem-team/bem-api/revisions/643398900e5d/schema)