Get / Delete Validation Run

Poll a validation run for status and accuracy with GET /v1/validation/runs/:id, or delete the run and its per-field results with DELETE on the same path.

GET /v1/validation/runs/{id} retrieves one validation run with its status, overall accuracy score, and comparison count; DELETE on the same path permanently removes the run and its per-field results. A validation run is a benchmark of a job run against Ground Truth, so this endpoint is where you poll until benchmarking finishes and the score is ready.

After creating a validation run, poll this endpoint until the status field transitions from pending or running to completed or failed. Once completed, the accuracy field contains the overall score (0-1) and total_comparisons shows how many field-level comparisons were made.

The response includes links.results which points directly to the per-field results endpoint. Once the run reaches completed status, follow this link to retrieve the granular comparison data including match types, similarity scores, and LLM judge verdicts.

Deleting a validation run permanently removes all per-field results. The Ground Truth dataset and the original job run are not affected. Use DELETE only when you want to clean up outdated or erroneous runs.

Pair this endpoint with Create Validation Run for the create-then-poll workflow, or with List Validation Runs to find specific runs by recency. Comparing the accuracy values of multiple runs against the same Ground Truth dataset is the primary way to track extraction quality over time.

GET/v1/validation/runs/{id}

Response

Response fields (GET)

idstringValidation run UUID.

namestringRun name.

statusstringRun status: pending, running, completed, or failed.

dataspace_run_idstring | nullUUID of the job run being validated.

golden_sample_idstringUUID of the Ground Truth dataset.

accuracynumber | nullOverall accuracy score (0–1) once completed.

total_comparisonsinteger | nullTotal field comparisons made.

created_atstringISO 8601 creation timestamp.

completed_atstring | nullISO 8601 completion timestamp.

linksobjectRelated resource URLs (self, results).

Response (GET)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Q1 Invoice accuracy check",
  "status": "completed",
  "dataspace_run_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "golden_sample_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "accuracy": 0.94,
  "total_comparisons": 250,
  "created_at": "2024-09-14T10:32:00.000Z",
  "completed_at": "2024-09-14T10:35:00.000Z",
  "links": {
    "self": "/v1/validation/runs/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "results": "/v1/validation/runs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/results"
  }
}

Response (DELETE)

{
  "deleted": true
}

Errors

Error responses

401unauthorizedMissing or invalid API key.

404not_foundValidation run not found or does not belong to your organization.

429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

List Validation Runs

Validation Results

Create a Validation Run