---
title: "Run Evaluation"
method: POST
path: "/v1/evaluations/run"
tags: ["evaluations"]
---

# Run Evaluation

`POST /v1/evaluations/run`

## Request

- Base URL: `https://api.vlm.run` (the document declares no server; this is the origin it was published from)
- URL: `https://api.vlm.run/v1/evaluations/run`
- Auth: HTTP bearer

Run evaluation with pluggable evaluators (field_accuracy, fuzzy_field_match, llm_judge, equals_expected). Set infer_corrections=true for notes-only feedback. Returns immediately with status=running. Poll by ID for completion.

## Request body

- RunEvaluationRequest: Request body for POST /evaluations/run.
  - `source_type` string, required: 'agent', 'request_domain', or 'skill'
  - `source_id` string, required: Agent ID, domain name, or skill ID
  - `source_label` string, required: Display label for the source
  - `model` string, nullable: Model used to produce the evaluated responses (e.g. 'vlmrun-orion-1:fast'). Stored with the run and reported in the performance section.
  - `execution_ids` string[], nullable: Agent execution IDs to evaluate
  - `request_ids` string[], nullable: Request IDs to evaluate
  - `skill_ids` string[], nullable: Skill IDs to evaluate
  - `data_from` string, nullable: ISO date filter start
  - `data_to` string, nullable: ISO date filter end
  - `evaluators` string[]: Evaluators to run; each produces its own section in the response.
  - `infer_corrections` boolean: Use LLM to produce corrected JSON from notes-only feedback.
  - `fields` string[], nullable: Restrict evaluation to these field names (top-level keys or dotted leaf-path prefixes, e.g. ['name', 'address', 'items']). When omitted, all fields are evaluated.
  - `skip_null_expected` boolean: When true (default), fields where the ground-truth (expected) value is null are excluded from evaluation. This avoids penalizing the model for extracting values that the ground-truth left empty.

## Response `200`

Successful Response

- object

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/vlm/apis/vlm-run-unified-server.md) · [All operations](https://skmtc.dev/vlm/apis/vlm-run-unified-server/llms.txt) · [OpenAPI document](https://skmtc.dev/vlm/apis/vlm-run-unified-server/revisions/4a68ab36546b?raw)