Skip to main content

Ground Truth Entries

List, add, or delete ground truth entries with the /v1/quality/ground-truth entries endpoints. Each entry pairs a document with its verified field values.

Ground truth entries are the individual verified data points inside a ground truth dataset: each entry pairs a document_id with the expected_data a correct extraction should produce for that document. Use the entries endpoints to list, add, and delete them, building the gold standard that benchmark runs score extraction accuracy against.

The typical workflow is: extract a set of representative documents, manually verify the correct value for each schema field, then POST one entry per document. When a benchmark runs, it compares the extracted value for each field against the matching key in expected_data and reports per-field accuracy.

Each entry maps a document_id to an expected_data object containing the verified field values. Field keys in expected_data should match the field names used in your extraction schema for accurate benchmark comparisons.
GET/v1/quality/ground-truth/:datasetId/entries

Response (List entries)

Response fields

dataarrayArray of entry objects.
data[].idstringEntry UUID.
data[].document_idstringDocument this entry corresponds to.
data[].expected_dataobjectKey-value map of verified field values.
data[].notesstring | nullOptional notes about this entry.
data[].created_atstringISO 8601 creation timestamp.

Response

{
  "data": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "document_id": "doc_abc123",
      "expected_data": {
        "vendor_name": "Acme Corp",
        "total_amount": 14250.00,
        "invoice_number": "INV-2024-0847"
      },
      "notes": null,
      "created_at": "2024-09-05T12:00:00.000Z"
    }
  ]
}
POST/v1/quality/ground-truth/:datasetId/entries

Body parameters

document_id*stringDocument this entry corresponds to.
expected_data*objectKey-value map of verified field values.
notesstringOptional notes about this entry.

Response (Add entry)

Response fields (201 Created)

idstringEntry UUID.
document_idstringDocument ID.
expected_dataobjectSaved field values.
notesstring | nullOptional notes.
created_atstringISO 8601 creation timestamp.

Response (POST entry)

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "document_id": "doc_abc123",
  "expected_data": {
    "vendor_name": "Acme Corp",
    "total_amount": 14250.00,
    "invoice_number": "INV-2024-0847"
  },
  "notes": null,
  "created_at": "2024-09-05T12:00:00.000Z"
}
DELETE/v1/quality/ground-truth/:datasetId/entries/:entryId

Response (Delete entry)

Response fields

deletedbooleanAlways true on success.

Response (DELETE entry)

{ "deleted": true }

Errors

Error responses

401unauthorizedMissing or invalid API key.
404not_foundDataset or entry not found for your workspace.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

Get Dataset with Samples
Start a Benchmark Run
Benchmark Results