List Golden Samples

List golden sample datasets with GET /v1/validation/ground-truth. Each holds verified per-field expected values that validation runs score a job run against.

This namespace is Benchmarks (the /v1/validation namespace): measuring how accurately a completed job run extracted data, by comparing its output against manually verified expected values. It is not the in-pipeline validation checks (see the Structuring API) that gate individual results before delivery — those keep the Validation name. GET /v1/validation/ground-truth lists the golden samples those accuracy measurements run against.

A golden sample (shown as Ground Truth in the platform) is a curated set of verified document-field value pairs: each entry names a document_id, a field_name, and the expected_value a correct extraction should produce. Every golden sample is bound to exactly one schema via user_schema_id — the schema whose fields the expected values describe — so a validation run always compares like with like. API payloads reference a dataset through the golden_sample_id field.

Do not confuse golden samples with the benchmark datasets under [/v1/quality/ground-truth](list-quality-datasets). Both store verified values, but a /v1/quality dataset holds one expected_data object per document and feeds repeatable benchmark runs, while a golden sample holds individual per-field expected values and scores one specific Structuring Run (a job run) via POST /v1/validation/runs.

The list returns every golden sample in your organization, newest first, in a single response — there are no pagination parameters on this endpoint. entry_count is the number of expected values stored on the sample (one per document-field pair). Golden samples are curated in the Talonic platform (Review → Benchmarks); through the public API you list them, inspect their expected values, delete them, and run benchmarks against them.

A typical integration lists datasets, picks the one matching the schema of the Structuring Run it wants to score, then passes its id as golden_sample_id to [POST /v1/validation/runs](create-validation-run). Because each dataset is schema-bound, filter client-side on user_schema_id to find the dataset that matches the run you are validating.

curl https://api.talonic.com/v1/validation/ground-truth \
  -H "Authorization: Bearer tlnc_..."

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Invoice Validation Set",
      "user_schema_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "entry_count": null,
      "created_at": "2024-08-01T00:00:00.000Z",
      "updated_at": "2024-08-01T00:00:00.000Z",
      "links": {
        "self": "/v1/validation/ground-truth/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  ]
}

Errors