---
title: "Start a benchmark run"
method: POST
path: "/v1/quality/benchmarks"
tags: ["Benchmarks"]
---

# Start a benchmark run

`POST /v1/quality/benchmarks`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/quality/benchmarks`
- Auth: HTTP bearer

Start an asynchronous benchmark run that evaluates extraction output
against a ground truth dataset. The run is created with status
`queued`; `documents_total` is set to the dataset's entry count and
accuracy fields stay null until the run completes. Poll
`GET /v1/quality/benchmarks/{id}` for progress and read per-document
outcomes from `GET /v1/quality/benchmarks/{id}/results`.

## Request body

- object
  - `dataset_id` string, uuid, required: Ground truth dataset to benchmark against.
  - `user_schema_id` string, uuid, required: User schema that defines the fields to evaluate.
  - `name` string: Human-readable name for this run. Defaults to "Benchmark YYYY-MM-DD".

## Response `201`

Benchmark run created with status `queued`.

- BenchmarkResponse
  - `id` string, uuid, required
  - `name` string, nullable
  - `dataset_id` string, uuid, nullable
  - `user_schema_id` string, uuid, nullable
  - `status` string, required: Benchmark run status.
  - `accuracy_overall` number, float, nullable
  - `accuracy_by_field` object, nullable
  - `documents_processed` integer, nullable
  - `documents_total` integer, nullable
  - `duration_ms` integer, nullable
  - `accuracy_delta` number, float, nullable: Change in overall accuracy vs the compared run.
  - `compared_to_run_id` string, uuid, nullable
  - `created_at` string, date-time
  - `completed_at` string, date-time, nullable
  - `links` object
    - `self` string
    - `results` string

## Other responses

- `400`: The request is invalid.
- `401`: Missing or invalid API key.
- `404`: The requested resource was not found.
- `429`: Daily rate limit exceeded.

---

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