---
title: "Run a verifier to check whether an output meets its criterion."
method: POST
path: "/verifiers/{verifier_id}/runs"
tags: ["verifiers"]
---

# Run a verifier to check whether an output meets its criterion.

`POST /verifiers/{verifier_id}/runs`

## Request

- Base URL: `https://api.goodeye.dev/v1`
- URL: `https://api.goodeye.dev/v1/verifiers/{verifier_id}/runs`
- Auth: none declared

Runs the judge against ``inputs`` (and optional ``media_url``). Path ``verifier_id`` is a Verifier UUID, or ``system:<name>`` for platform-managed verifiers. Anonymous callers may run a Verifier UUID iff it appears in some live ``template_versions.verifier_snapshots`` (publicly-runnable gate); spend is gated by the credit ledger. Caller-shape errors return 400 with no row written; runtime errors return 201 with ``status="error"`` and an ``error_code`` of ``runtime_error``, ``verifier_unavailable``, or ``timeout``. Returns ``{verifier_run_id, anonymous_verifier_run_id, verifier_id, version, status, passed, reasoning, duration_ms, created_at}`` (one of ``verifier_run_id`` or ``anonymous_verifier_run_id`` populated). A successful run attributed to a skill you own also echoes that skill's ``skill_id``.

## Path parameters

- `verifier_id` string, required

## Request body

- RunVerifierBody: Request body for ``POST /verifiers/{verifier_id}/runs``. ``inputs`` keys must match the version's ``input_fields`` exactly. ``media_url`` is required for ``text_image`` and ``image`` contracts, and rejected for ``text``. Caller-shape errors return 400 with no run row written; judge runtime errors return 201 with ``status="error"``.
  - `version` integer, nullable: Pin to a specific verifier version; defaults to the current version.
  - `inputs` object: Map keyed by the version's ``input_fields``. Keys must match the deployed list exactly; values must be non-empty strings.
  - `media_url` string, nullable: Public HTTPS image URL. Required for ``text_image`` and ``image`` contracts, rejected for ``text``.
  - `skill_id` string, nullable: Optional skill UUID for provenance. Access-checked: a skill the caller cannot see surfaces as 404.
  - `skill_version` integer, nullable: Skill version invoking this run, paired with ``skill_id``.
  - `skill_ref` string, nullable: Free-form skill label (slug, name) for human-readable provenance.
  - `run_id` string, nullable: Optional caller-supplied correlation ID stamped onto the run row.

## Response `201`

Successful Response

- object

## Other responses

- `400`: Caller-shape error (bad inputs, missing or excess fields, wrong media).
- `404`: Verifier or referenced skill not visible to caller.
- `422`: Validation Error

---

[API](https://skmtc.dev/goodeye/apis/goodeye-api.md) · [All operations](https://skmtc.dev/goodeye/apis/goodeye-api/llms.txt) · [OpenAPI document](https://skmtc.dev/goodeye/apis/goodeye-api/revisions/547cb8bb6ede?raw)