Get / Delete Validation Run

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

GET /v1/validation/runs/{id} retrieves one validation run with its status and metadata; 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 a golden sample, so this endpoint is where you poll until benchmarking finishes and the per-field results are ready to read.

After a run is created, poll this endpoint until the status field reaches a terminal state: the lifecycle is pending → queued → processing → completed or failed. Runs created through the public API return already completed or failed, so polling is only needed for runs launched elsewhere.

Once status is completed, accuracy (0-1, weighted across all fields and documents), total_comparisons and the per-field field_accuracy breakdown are populated. Follow links.results to [the per-field results](get-validation-results) when you need row-level detail — for example to list every mismatch for one field.

Pair this endpoint with Create Validation Run for the register-then-poll workflow, or with List Validation Runs to find specific runs by recency. Because the list endpoint returns only the newest 100 runs, deleting superseded runs here also keeps your full history reachable through the list.

The run object doubles as an audit record: created_at and completed_at bound when the benchmark ran, dataspace_run_id ties the score to the exact Structuring Run that produced the output, and golden_sample_id ties it to the exact reference dataset. Store the run id alongside your own release or deployment records so a later accuracy question ("what did we measure before the schema change?") resolves to one GET instead of an archaeology session.

curl https://api.talonic.com/v1/validation/runs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer tlnc_..."

Response

{
  "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.9412,
  "total_comparisons": 68,
  "matched_documents": 17,
  "unmatched_golden": 0,
  "unmatched_dataset": 2,
  "field_accuracy": { "invoice_number": { "total": 17, "exact": 17, "partial": 0, "mismatch": 0, "missing_actual": 0, "missing_expected": 0, "both_empty": 0, "accuracy": 1 } },
  "error_message": null,
  "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"
  }
}

{
  "deleted": true
}

Errors